Merge "DfC certificate handling clarifications"
[dcaegen2.git] / docs / sections / services / dfc / certificates.rst
1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3
4 Certificates
5 ============
6
7 Configuration of Certificates in test environment(For FTP over TLS):
8
9 DFC supports two protocols: FTPES and SFTP.
10 For FTPES, it is mutual authentication with certificates.
11 In our test environment, we use vsftpd to simulate xNF, and we generate self-signed
12 keys & certificates on both vsftpd server and DFC.
13
14 1. Generate key/certificate with openssl for DFC:
15 -------------------------------------------------
16 .. code:: bash
17
18     openssl genrsa -out dfc.key 2048
19     openssl req -new -out dfc.csr -key dfc.key
20     openssl x509 -req -days 365 -in dfc.csr -signkey dfc.key -out dfc.crt
21
22 2. Generate key & certificate with openssl for vsftpd:
23 ------------------------------------------------------
24 .. code:: bash
25
26    openssl genrsa -out ftp.key 2048
27    openssl req -new -out ftp.csr -key ftp.key
28    openssl x509 -req -days 365 -in ftp.csr -signkey ftp.key -out ftp.crt
29
30 3. Configure java keystore in DFC:
31 ----------------------------------
32 We have two keystore files, one for TrustManager, one for KeyManager.
33
34 **For TrustManager:**
35
36 1. First, convert your certificate in a DER format :
37
38  .. code:: bash
39
40    openssl x509 -outform der -in ftp.crt -out ftp.der
41
42 2. And after, import it in the keystore :
43
44  .. code:: bash
45
46    keytool -import -alias ftp -keystore ftp.jks -file ftp.der
47
48 **For KeyManager:**
49
50 1. First, create a jks keystore:
51
52  .. code:: bash
53
54     keytool -keystore dfc.jks -genkey -alias dfc
55
56 2. Second, import dfc.crt and dfc.key to dfc.jks. This is a bit troublesome.
57
58  1). Step one: Convert x509 Cert and Key to a pkcs12 file
59
60  .. code:: bash
61
62     openssl pkcs12 -export -in dfc.crt -inkey dfc.key -out dfc.p12 -name [some-alias]
63
64  Note: Make sure you put a password on the p12 file - otherwise you'll get a null reference exception when you try to import it.
65
66  Note 2: You might want to add the -chainoption to preserve the full certificate chain.
67
68  2). Step two: Convert the pkcs12 file to a java keystore:
69
70  .. code:: bash
71
72     keytool -importkeystore -deststorepass [changeit] -destkeypass [changeit] -destkeystore dfc.jks -srckeystore dfc.p12 -srcstoretype PKCS12 -srcstorepass [some-password] -alias [some-alias]
73
74 4. Update existing jks.b64 files
75 ---------------------------------
76
77 Copy the existing jks from the DFC container to a local environment.
78
79  .. code:: bash
80  
81    docker cp <DFC container>:/opt/app/datafile/config/ftp.jks .
82    docker cp <DFC container>:/opt/app/datafile/config/dfc.jks .
83
84  .. code:: bash
85  
86    openssl base64 -in ftp.jks -out ftp.jks.b64
87    openssl base64 -in dfc.jks -out dfc.jks.b64
88
89  .. code:: bash
90  
91    chmod 755 ftp.jks.b64
92    chmod 755 dfc.jks.b64
93
94 Copy the new jks.64 files from local environment to the DFC container.
95
96  .. code:: bash
97  
98    docker cp ftp.jks.b64 <DFC container>:/opt/app/datafile/config/
99    docker cp dfc.jks.b64 <DFC container>:/opt/app/datafile/config/
100
101 Finally
102
103  .. code:: bash
104  
105    docker restart <DFC container>
106
107 5. Configure vsftpd:
108 --------------------
109     update /etc/vsftpd/vsftpd.conf:
110
111   .. code-block:: bash
112
113       rsa_cert_file=/etc/ssl/private/ftp.crt
114       rsa_private_key_file=/etc/ssl/private/ftp.key
115       ssl_enable=YES
116       allow_anon_ssl=NO
117       force_local_data_ssl=YES
118       force_local_logins_ssl=YES
119
120       ssl_tlsv1=YES
121       ssl_sslv2=YES
122       ssl_sslv3=YES
123
124       require_ssl_reuse=NO
125       ssl_ciphers=HIGH
126
127       require_cert=YES
128       ssl_request_cert=YES
129       ca_certs_file=/home/vsftpd/myuser/dfc.crt
130
131 6. Configure config/datafile_endpoints.json:
132 --------------------------------------------
133    Update the file accordingly:
134
135   .. code-block:: javascript
136
137             "ftpesConfiguration": {
138                 "keyCert": "/config/dfc.jks",
139                 "keyPassword": "[yourpassword]",
140                 "trustedCA": "/config/ftp.jks",
141                 "trustedCAPassword": "[yourpassword]"
142             }
143
144 7. Other conditions
145 ---------------------------------------------------------------------------
146    This has been tested with vsftpd and dfc, with self-signed certificates.
147    In real deployment, we should use ONAP-CA signed certificate for DFC, and vendor-CA signed certificate for xNF