Revise certificate creation procedure
[federation.git] / docs / config.rst
1 .. ===============LICENSE_START=======================================================
2 .. Acumos CC-BY-4.0
3 .. ===================================================================================
4 .. Copyright (C) 2017 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
5 .. ===================================================================================
6 .. This Acumos documentation file is distributed by AT&T and Tech Mahindra
7 .. under the Creative Commons Attribution 4.0 International License (the "License");
8 .. you may not use this file except in compliance with the License.
9 .. You may obtain a copy of the License at
10 ..
11 .. http://creativecommons.org/licenses/by/4.0
12 ..
13 .. This file is distributed on an "AS IS" BASIS,
14 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 .. See the License for the specific language governing permissions and
16 .. limitations under the License.
17 .. ===============LICENSE_END=========================================================
18
19 ======================================
20 Federation Gateway Configuration Guide
21 ======================================
22
23
24 This document explains the steps required to configure two Acumos
25 instances to be peers so that they can communicate via their
26 Federation Gateway components.  Gateways use certificates for mutual
27 SSL authentication.
28
29 An overview of the general process is here:
30 `Mutual SSL Authentication
31 <https://www.codeproject.com/Articles/326574/An-Introduction-to-Mutual-SSL-Authentication/>`_
32
33 Assistance with the detailed process is here:
34 `How to setup your own CA with OpenSSL
35 <https://gist.github.com/Soarez/9688998>`_
36
37 Background
38 ----------
39
40 The asymmetric encryption technique used here is based on two keys: a
41 message that gets encrypted with one key can be decrypted with the
42 other key. We call one the private key and the other the public key,
43 because when used in two-party communication we keep one (the private
44 key) and we give one away (the public key). The one we give away needs
45 to be certified; i.e., others need to be sure the key can be
46 trusted. For that we send the public key to a certificate authority
47 (CA) in the form of a certificate signing request (CSR).  The CA signs
48 this (creates some hash) with their private key. Then everyone who has
49 the CA public key (who trusts the CA) will accept our signed-by-the-CA
50 public key, and this chain of trust can go on recursively.  The result
51 is that our public key gets packed in a certificate signed by that CA
52 and now we can use it/share it with others.
53
54 Each peer gateway is provisioned with a PKCS12 key store holding a
55 private key and a certificate, which is the matching public key signed
56 by a certificate authority.  The mutual authentication process
57 proceeds as follows.  A federation peer C (playing the client role in
58 this example) attempts a connection to peer S (playing the server role
59 in this example).  To establish a secure communication channel, peer S
60 first sends its certificate.  The receipt by C of the S certificate
61 allows C to verify S's identity.  After this step is successful, peer
62 S asks peer C for C's certificate.  Peer S then checks the identity of
63 peer C based on the certificate.  If that succeeds, the channel is
64 secure.  After this TLS handshake process has completed, peer S
65 searches its peer repository (internal configuration) for the fully
66 qualified host name from C's certificate, and allows the exchange of
67 information if a match is found.
68
69
70 Overview
71 --------
72
73 The following tasks are required for configuration of each Acumos host:
74
75 * Create a certificate signing request
76 * Obtain a signed certificate, either by purchasing it or signing the requset with a local authority
77 * Install the signed certificate in the gateway deployment environment
78 * Configure the gateway using the Portal administration interface.
79
80
81 Create Certificates
82 -------------------
83
84 These instructions create appropriate certificates suitable for
85 development and testing environments ONLY, not for production
86 environments.  To avoid the delay and expense of purchasing a signed
87 certificate from a well-known certificate authority, this creates a
88 new certificate authority (CA) and adds the appropriate certificate to
89 a trust store.
90
91 These following instructions use the ``openssl`` command-line tool,
92 which is available on Linux hosts.  This scenario was developed using
93 Ubuntu version 16.04.  The instructions use shell-style variables
94 (e.g., ``$VAR``) to indicate where a value must be supplied and
95 reused.
96
97 Step 1: Determine the fully qualified domain name of the peer (FQDN)
98 and choose a password (6 characters or more). Store these values in
99 shell variables ``ACUMOS_HOST`` and ``ACUMOS_PASS`` for use in the
100 commands below.  For example::
101
102   export ACUMOS_HOST="myserver.mymodels.org"
103   export ACUMOS_PASS="mykey123456"
104
105 Step 2: Because a new certificate authorithy (CA) will be created
106 here, openssl requires a configuration file ``openssl.cnf``.  Create
107 this file using the template below, and in the ``[alt_names]``
108 section replace the string ``<acumos-host>`` with the FQDN you chose
109 above.
110
111 Step 3: Create the Acumos CA private key::
112
113   openssl genrsa -des3 -out acumosCA.key -passout pass:$ACUMOS_PASS 4096
114
115 Step 4: Create the Acumos CA certificate. You may wish to use
116 different values (i.e., not "Unspecified") in this command, just be
117 consistent in later commands::
118
119   openssl req -x509 -new -nodes -key acumosCA.key -sha256 -days 1024 \
120     -config openssl.cnf -out acumosCA.crt -passin pass:$ACUMOS_PASS \
121     -subj "/C=US/ST=Unspecified/L=Unspecified/O=Acumos/OU=Acumos/CN=$ACUMOS_HOST"
122
123 Step 5: Create a JKS-format truststore with the Acumos CA certificate::
124
125   keytool -import -file acumosCA.crt -alias acumosCA -keypass $ACUMOS_PASS \
126       -keystore acumosTrustStore.jks -storepass $ACUMOS_PASS -noprompt
127
128 Step 6: Create the server private key::
129
130   openssl genrsa -out acumos.key -passout pass:$ACUMOS_PASS 4096
131
132 Step 7: Create a certificate signing request (CSR) for your FQDN.
133 Please note the C, ST, L, O, OU and CN key-value pairs must match what
134 was used above::
135
136   openssl req -new -key acumos.key -passin pass:$ACUMOS_PASS -out acumos.csr \
137     -subj "/C=US/ST=Unspecified/L=Unspecified/O=Acumos/OU=Acumos/CN=$ACUMOS_HOST"
138
139 Step 8: Sign the CSR with the Acumos CA certificate to yield a server certificate::
140
141   openssl ca -config openssl.cnf -passin pass:$ACUMOS_PASS -in acumos.csr -out acumos.crt
142
143 Step 9: Copy the server private key and certificate to a plain text
144 file ``acumos.txt``. The private key should appear first, followed by
145 the certificate. The finished file should have this structure::
146   
147   -----BEGIN RSA PRIVATE KEY-----
148   (Private Key: acumos.key contents)
149   -----END RSA PRIVATE KEY-----
150   -----BEGIN CERTIFICATE-----
151   (SSL certificate: acumos.crt contents)
152   -----END CERTIFICATE-----
153   
154 Step 10: Create a PKCS12 format keystore with the server key and certificate::
155   
156   openssl pkcs12 -export -in acumos.txt -passout pass:$ACUMOS_PASS -out acumos.pkcs12
157
158 Step 11: Copy the JKS and PKCS12 files to the machine where the
159 federation component runs and configure them:
160
161 * Enter the path to the JKS file in key ``trust-store``
162 * Enter the password for the JKS file in key ``trust-store-password``
163 * Enter the path to the PKCS12 file in key ``key-store``
164 * Enter the password for the  PKCS12 file in key ``key-store-password``
165 * Enter the key store type in key ``key-store-type`` with value ``PKCS12``
166
167   
168 Final Checklist
169 ---------------
170
171 These are the prerequisites for Acumos instance A (``hostA.name.org``)
172 to pull models from its Acumos peer B (``hostB.name.org``):
173  
174 #. Federation gateways are running on both instances
175 #. Gateway A has a PKCS12 file containing a certificate for ``hostA.name.org`` and signed by authority CA-1
176 #. Gateway A deployment configuration has the path to the PKCS12 file in key ``federation.ssl.key-store``
177 #. Gateway A has a trust store file that includes the signing certificate for authority CA-2
178 #. Gateway A deployment configuration has the path to the trust store file in key ``federation.ssl.trust-store``
179 #. Gateway A is configured with peer B's FQDN (``hostB.name.org``) and public gateway URL (``https://hostB.name.org:12345``)
180 #. Gateway B has with a PCKS12 file containing a certificate for ``hostB.name.org`` and signed by authority CA-2
181 #. Gateway B deployment configuration has the path to the PKCS12 file in key ``federation.ssl.key-store``
182 #. Gateway B has a trust store file that includes the signing certificate for authority CA-1
183 #. Gateway B deployment configuration has the path to the trust store file in key ``federation.ssl.trust-store``
184 #. Gateway B is configured with peer A's FQDN (``hostA.name.org``) and public gateway URL (``https://hostA.name.org:54321``)
185
186 Please note that a PKCS12 file is a store, i.e. it contains private
187 key and associated certificates in a binary form (and not just
188 certificates).
189
190 Troubleshooting
191 ---------------
192
193 First, use the following steps to extract certificates and keys to
194 test connections manually.
195
196 Extract the CA certificate created above in PEM format::
197
198   keytool -export -alias acumos -file acumos-ca.crt -keystore acumosTrustStore.jks
199   openssl x509 -inform der -in acumos-ca.crt -out acumos-ca.pem
200   
201 Extract the signed certificate for the client host attempting the
202 connection in PEM format::
203
204   openssl pkcs12 -in acumos.p12 -clcerts -nokeys -out  acumos.pem
205
206 Extract the private key for the client host attempting the connection::
207
208   openssl pkcs12 -in acumos.p12 -nocerts -out acumos.key  
209   
210 Next run the following command to test the certificates used to
211 establish a connection to remote peer ``yourserver.yourmodels.org`` at
212 port 9084 from server ``myserver.mymodels.org``. The certificate files
213 used below were created by the procedure above for host
214 ``myserver.mymodels.org``::
215
216   openssl s_client -connect yourserver.yourmodels.org:9084 -cert acumos.pem -key acumos.key -CAfile acumos-ca.pem
217
218 You must enter the key phrase, then the connection attempt can begin.
219
220 Finally use the command-line tool ``curl`` to test whether the remote
221 host is ready to accept connections.  This command uses the ``-k``
222 option to allow insecure connections, so the certificate authority is
223 not required here::
224
225   curl -vk --cert acumos.pem:mykey123456 --key acumos.key https://yourserver.yourmodels.org:9084/ping
226
227
228 Template openssl.cnf
229 --------------------
230
231 ::
232
233   # This is a customized OpenSSL configuration file. Commented out sections below
234   # are included for testing/clarity for now, and will be removed later once the
235   # specific comments that need to be retained for clarity are determined.
236   #
237
238   # This definition stops the following lines choking if HOME isn't
239   # defined.
240   HOME                    = .
241   RANDFILE                = $ENV::HOME/.rnd
242
243   # Extra OBJECT IDENTIFIER info:
244   #oid_file               = $ENV::HOME/.oid
245   oid_section             = new_oids
246
247   # To use this configuration file with the "-extfile" option of the
248   # "openssl x509" utility, name here the section containing the
249   # X.509v3 extensions to use:
250   extensions            = v3_req
251   # (Alternatively, use a configuration file that has only
252   # X.509v3 extensions in its main [= default] section.)
253
254   [ new_oids ]
255
256   # We can add new OIDs in here for use by 'ca', 'req' and 'ts'.
257   # Add a simple OID like this:
258   # testoid1=1.2.3.4
259   # Or use config file substitution like this:
260   # testoid2=${testoid1}.5.6
261
262   # Policies used by the TSA examples.
263   tsa_policy1 = 1.2.3.4.1
264   tsa_policy2 = 1.2.3.4.5.6
265   tsa_policy3 = 1.2.3.4.5.7
266
267   ####################################################################
268   [ ca ]
269   default_ca      = CA_default            # The default ca section
270
271   ####################################################################
272   [ CA_default ]
273
274   dir             = .                     # Where everything is kept
275   certs           = $dir/certs            # Where the issued certs are kept
276   crl_dir         = $dir/crl              # Where the issued crl are kept
277   database        = $dir/index.txt        # database index file.
278   #unique_subject = no                    # Set to 'no' to allow creation of
279                                           # several ctificates with same subject.
280   new_certs_dir   = $dir/newcerts         # default place for new certs.
281
282   certificate     = $dir/certs/acumos_ca.crt     # The CA certificate
283   serial          = $dir/serial           # The current serial number
284   crlnumber       = $dir/crlnumber        # the current crl number
285                                           # must be commented out to leave a V1 CRL
286   crl             = $dir/crl.pem          # The current CRL
287   private_key     = $dir/private/acumos_ca.key   # The private key
288   RANDFILE        = $dir/private/.rand    # private random number file
289
290   x509_extensions = usr_cert              # The extentions to add to the cert
291
292   # Comment out the following two lines for the "traditional"
293   # (and highly broken) format.
294   name_opt        = ca_default            # Subject Name options
295   cert_opt        = ca_default            # Certificate field options
296
297   # Extension copying option: use with caution.
298   copy_extensions = copy
299
300   # Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
301   # so this is commented out by default to leave a V1 CRL.
302   # crlnumber must also be commented out to leave a V1 CRL.
303   # crl_extensions        = crl_ext
304
305   default_days    = 365                   # how long to certify for
306   default_crl_days= 30                    # how long before next CRL
307   default_md      = default               # use public key default MD
308   preserve        = no                    # keep passed DN ordering
309
310   # A few difference way of specifying how similar the request should look
311   # For type CA, the listed attributes must be the same, and the optional
312   # and supplied fields are just that :-)
313   policy          = policy_match
314
315   # For the CA policy
316   [ policy_match ]
317   countryName             = match
318   stateOrProvinceName     = match
319   organizationName        = match
320   organizationalUnitName  = optional
321   commonName              = supplied
322   emailAddress            = optional
323
324   # For the 'anything' policy
325   # At this point in time, you must list all acceptable 'object'
326   # types.
327   [ policy_anything ]
328   countryName             = optional
329   stateOrProvinceName     = optional
330   localityName            = optional
331   organizationName        = optional
332   organizationalUnitName  = optional
333   commonName              = supplied
334   emailAddress            = optional
335
336   ####################################################################
337   [ req ]
338   default_bits            = 2048
339   default_keyfile         = privkey.pem
340   distinguished_name      = req_distinguished_name
341   attributes              = req_attributes
342   x509_extensions = v3_ca # The extentions to add to the self signed cert
343
344   # Passwords for private keys if not present they will be prompted for
345   # input_password = secret
346   # output_password = secret
347
348   # This sets a mask for permitted string types. There are several options.
349   # default: PrintableString, T61String, BMPString.
350   # pkix   : PrintableString, BMPString (PKIX recommendation before 2004)
351   # utf8only: only UTF8Strings (PKIX recommendation after 2004).
352   # nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).
353   # MASK:XXXX a literal mask value.
354   # WARNING: ancient versions of Netscape crash on BMPStrings or UTF8Strings.
355   string_mask = utf8only
356
357   req_extensions = v3_req # The extensions to add to a certificate request
358
359   [ req_distinguished_name ]
360   countryName                     = Country Name (2 letter code)
361   countryName_default             = US
362   countryName_min                 = 2
363   countryName_max                 = 2
364
365   stateOrProvinceName             = State or Province Name (full name)
366   stateOrProvinceName_default     = Some-State
367
368   localityName                    = Locality Name (eg, city)
369
370   0.organizationName              = Organization Name (eg, company)
371   0.organizationName_default      = Internet Widgits Pty Ltd
372
373   # we can do this but it is not needed normally :-)
374   #1.organizationName             = Second Organization Name (eg, company)
375   #1.organizationName_default     = World Wide Web Pty Ltd
376
377   organizationalUnitName          = Organizational Unit Name (eg, section)
378   #organizationalUnitName_default =
379
380   commonName                      = Common Name (e.g. server FQDN or YOUR name)
381   commonName_max                  = 64
382
383   emailAddress                    = Email Address
384   emailAddress_max                = 64
385
386   # SET-ex3                       = SET extension number 3
387
388   [ req_attributes ]
389   challengePassword               = A challenge password
390   challengePassword_min           = 4
391   challengePassword_max           = 20
392
393   unstructuredName                = An optional company name
394
395   [ usr_cert ]
396
397   # These extensions are added when 'ca' signs a request.
398
399   # This goes against PKIX guidelines but some CAs do it and some software
400   # requires this to avoid interpreting an end user certificate as a CA.
401
402   basicConstraints=CA:FALSE
403
404   # Here are some examples of the usage of nsCertType. If it is omitted
405   # the certificate can be used for anything *except* object signing.
406
407   # This is OK for an SSL server.
408   # nsCertType                    = server
409
410   # For an object signing certificate this would be used.
411   # nsCertType = objsign
412
413   # For normal client use this is typical
414   # nsCertType = client, email
415
416   # and for everything including object signing:
417   # nsCertType = client, email, objsign
418
419   # This is typical in keyUsage for a client certificate.
420   # keyUsage = nonRepudiation, digitalSignature, keyEncipherment
421
422   # This will be displayed in Netscape's comment listbox.
423   nsComment                       = "OpenSSL Generated Certificate"
424
425   # PKIX recommendations harmless if included in all certificates.
426   subjectKeyIdentifier=hash
427   authorityKeyIdentifier=keyid,issuer
428
429   # This stuff is for subjectAltName and issuerAltname.
430   # Import the email address.
431   # subjectAltName=email:copy
432   # An alternative to produce certificates that aren't
433   # deprecated according to PKIX.
434   # subjectAltName=email:move
435
436   # Copy subject details
437   # issuerAltName=issuer:copy
438
439   #nsCaRevocationUrl              = http://www.domain.dom/ca-crl.pem
440   #nsBaseUrl
441   #nsRevocationUrl
442   #nsRenewalUrl
443   #nsCaPolicyUrl
444   #nsSslServerName
445
446   # This is required for TSA certificates.
447   # extendedKeyUsage = critical,timeStamping
448
449   [ v3_req ]
450
451   # Extensions to add to a certificate request
452
453   basicConstraints = CA:FALSE
454   keyUsage = nonRepudiation, digitalSignature, keyEncipherment
455   subjectAltName = @alt_names
456   # Included these for openssl x509 -req -extfile
457   subjectKeyIdentifier=hash
458   authorityKeyIdentifier=keyid,issuer
459
460   [ alt_names ]
461
462   DNS.1 = <acumos-host>
463   # federation-service: for portal-be access to federation local port via expose
464   DNS.2 = federation-service
465
466   [ v3_ca ]
467
468
469   # Extensions for a typical CA
470
471
472   # PKIX recommendation.
473
474   subjectKeyIdentifier=hash
475
476   authorityKeyIdentifier=keyid:always,issuer
477
478   # This is what PKIX recommends but some broken software chokes on critical
479   # extensions.
480   #basicConstraints = critical,CA:true
481   # So we do this instead.
482   basicConstraints = CA:true
483
484   # Key usage: this is typical for a CA certificate. However since it will
485   # prevent it being used as an test self-signed certificate it is best
486   # left out by default.
487   # keyUsage = cRLSign, keyCertSign
488
489   # Some might want this also
490   # nsCertType = sslCA, emailCA
491
492   # Include email address in subject alt name: another PKIX recommendation
493   # subjectAltName=email:copy
494   # Copy issuer details
495   # issuerAltName=issuer:copy
496
497   # DER hex encoding of an extension: beware experts only!
498   # obj=DER:02:03
499   # Where 'obj' is a standard or added object
500   # You can even override a supported extension:
501   # basicConstraints= critical, DER:30:03:01:01:FF
502
503   [ crl_ext ]
504
505   # CRL extensions.
506   # Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.
507
508   # issuerAltName=issuer:copy
509   authorityKeyIdentifier=keyid:always
510
511   [ proxy_cert_ext ]
512   # These extensions should be added when creating a proxy certificate
513
514   # This goes against PKIX guidelines but some CAs do it and some software
515   # requires this to avoid interpreting an end user certificate as a CA.
516
517   basicConstraints=CA:FALSE
518
519   # Here are some examples of the usage of nsCertType. If it is omitted
520   # the certificate can be used for anything *except* object signing.
521
522   # This is OK for an SSL server.
523   # nsCertType                    = server
524
525   # For an object signing certificate this would be used.
526   # nsCertType = objsign
527
528   # For normal client use this is typical
529   # nsCertType = client, email
530
531   # and for everything including object signing:
532   # nsCertType = client, email, objsign
533
534   # This is typical in keyUsage for a client certificate.
535   # keyUsage = nonRepudiation, digitalSignature, keyEncipherment
536
537   # This will be displayed in Netscape's comment listbox.
538   nsComment                       = "OpenSSL Generated Certificate"
539
540   # PKIX recommendations harmless if included in all certificates.
541   subjectKeyIdentifier=hash
542   authorityKeyIdentifier=keyid,issuer
543
544   # This stuff is for subjectAltName and issuerAltname.
545   # Import the email address.
546   # subjectAltName=email:copy
547   # An alternative to produce certificates that aren't
548   # deprecated according to PKIX.
549   # subjectAltName=email:move
550
551   # Copy subject details
552   # issuerAltName=issuer:copy
553
554   #nsCaRevocationUrl              = http://www.domain.dom/ca-crl.pem
555   #nsBaseUrl
556   #nsRevocationUrl
557   #nsRenewalUrl
558   #nsCaPolicyUrl
559   #nsSslServerName
560
561   # This really needs to be in place for it to be a proxy certificate.
562   proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:3,policy:foo
563
564   ####################################################################
565   [ tsa ]
566
567   default_tsa = tsa_config1       # the default TSA section
568
569   [ tsa_config1 ]
570
571   # These are used by the TSA reply generation only.
572   dir             = ./demoCA              # TSA root directory
573   serial          = $dir/tsaserial        # The current serial number (mandatory)
574   crypto_device   = builtin               # OpenSSL engine to use for signing
575   signer_cert     = $dir/tsacert.pem      # The TSA signing certificate
576                                           # (optional)
577   certs           = $dir/cacert.pem       # Certificate chain to include in reply
578                                           # (optional)
579   signer_key      = $dir/private/tsakey.pem # The TSA private key (optional)
580
581   default_policy  = tsa_policy1           # Policy if request did not specify it
582                                           # (optional)
583   other_policies  = tsa_policy2, tsa_policy3      # acceptable policies (optional)
584   digests         = md5, sha1             # Acceptable message digests (mandatory)
585   accuracy        = secs:1, millisecs:500, microsecs:100  # (optional)
586   clock_precision_digits  = 0     # number of digits after dot. (optional)
587   ordering                = yes   # Is ordering defined for timestamps?
588                                   # (optional, default: no)
589   tsa_name                = yes   # Must the TSA name be included in the reply?
590                                   # (optional, default: no)
591   ess_cert_id_chain       = no    # Must the ESS cert id chain be included?
592                                   # (optional, default: no