Normalize to one trailing slash on Nexus URL
[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 The recommended practice here is to import the self-signed Acumos CA
129 certificate into an existing trust store. For example you can extend
130 the file "cacerts" that is included with a Java Runtime Engine (JRE)
131 distribution below directory "jre/lib/security" which usually uses the
132 password "changeit".
133
134 Step 6: Create the server private key::
135
136   openssl genrsa -out acumos.key -passout pass:$ACUMOS_PASS 4096
137
138 Step 7: Create a certificate signing request (CSR) for your FQDN.
139 Please note the C, ST, L, O, OU and CN key-value pairs must match what
140 was used above::
141
142   openssl req -new -key acumos.key -passin pass:$ACUMOS_PASS -out acumos.csr \
143     -subj "/C=US/ST=Unspecified/L=Unspecified/O=Acumos/OU=Acumos/CN=$ACUMOS_HOST"
144
145 Step 8: Sign the CSR with the Acumos CA certificate to yield a server certificate::
146
147   openssl ca -config openssl.cnf -passin pass:$ACUMOS_PASS -in acumos.csr -out acumos.crt
148
149 Step 9: Copy the server private key and certificate to a plain text
150 file ``acumos.txt``. The private key should appear first, followed by
151 the certificate. The finished file should have this structure::
152
153   -----BEGIN RSA PRIVATE KEY-----
154   (Private Key: acumos.key contents)
155   -----END RSA PRIVATE KEY-----
156   -----BEGIN CERTIFICATE-----
157   (SSL certificate: acumos.crt contents)
158   -----END CERTIFICATE-----
159
160 Step 10: Create a PKCS12 format keystore with the server key and certificate::
161
162   openssl pkcs12 -export -in acumos.txt -passout pass:$ACUMOS_PASS -out acumos.pkcs12
163
164 Step 11: Copy the JKS and PKCS12 files to the machine where the
165 federation component runs and configure them:
166
167 * Enter the path to the JKS file in key ``trust-store``
168 * Enter the password for the JKS file in key ``trust-store-password``
169 * Enter the path to the PKCS12 file in key ``key-store``
170 * Enter the password for the  PKCS12 file in key ``key-store-password``
171 * Enter the key store type in key ``key-store-type`` with value ``PKCS12``
172
173
174 Final Checklist
175 ---------------
176
177 These are the prerequisites for Acumos instance A (``hostA.name.org``)
178 to pull models from its Acumos peer B (``hostB.name.org``):
179
180 #. Federation gateways are running on both instances
181 #. Gateway A has a PKCS12 file containing a certificate for ``hostA.name.org`` and signed by authority CA-1
182 #. Gateway A deployment configuration has the path to the PKCS12 file in key ``federation.ssl.key-store``
183 #. Gateway A has a trust store file that includes the signing certificate for authority CA-2
184 #. Gateway A deployment configuration has the path to the trust store file in key ``federation.ssl.trust-store``
185 #. Gateway A is configured with peer B's FQDN (``hostB.name.org``) and public gateway URL (``https://hostB.name.org:12345``)
186 #. Gateway B has with a PCKS12 file containing a certificate for ``hostB.name.org`` and signed by authority CA-2
187 #. Gateway B deployment configuration has the path to the PKCS12 file in key ``federation.ssl.key-store``
188 #. Gateway B has a trust store file that includes the signing certificate for authority CA-1
189 #. Gateway B deployment configuration has the path to the trust store file in key ``federation.ssl.trust-store``
190 #. Gateway B is configured with peer A's FQDN (``hostA.name.org``) and public gateway URL (``https://hostA.name.org:54321``)
191
192 Please note that a PKCS12 file is a store, i.e. it contains private
193 key and associated certificates in a binary form (and not just
194 certificates).
195
196 Troubleshooting
197 ---------------
198
199 Inspect the certificate advertised by your server using this command::
200
201   openssl s_client -connect yourserver.yourmodels.org:9084
202
203 Look carefully at the "Certificate chain" section.  In case of error
204 you may see a message like this::
205
206   Verify return code: 21 (unable to verify the first certificate)
207
208 For advanced troubleshooting, use the following steps to extract
209 certificates and keys to test connections manually.
210
211 Extract the CA certificate created above in PEM format::
212
213   keytool -export -alias acumos -file acumos-ca.crt -keystore acumosTrustStore.jks
214   openssl x509 -inform der -in acumos-ca.crt -out acumos-ca.pem
215
216 Extract the signed certificate for the client host attempting the
217 connection in PEM format::
218
219   openssl pkcs12 -in acumos.p12 -clcerts -nokeys -out acumos.pem
220
221 Look at the signed certificate details, for example the expiration date::
222
223   openssl x509 -in acumos.pem -text -noout
224
225 Extract the private key for the client host attempting the connection::
226
227   openssl pkcs12 -in acumos.p12 -nocerts -out acumos.key
228
229 Next run the following command to test the certificates used to
230 establish a connection to remote peer ``yourserver.yourmodels.org`` at
231 port 9084 from server ``myserver.mymodels.org``. The certificate files
232 used below were created by the procedure above for host
233 ``myserver.mymodels.org``::
234
235   openssl s_client -connect yourserver.yourmodels.org:9084 -cert acumos.pem -key acumos.key -CAfile acumos-ca.pem
236
237 You must enter the key phrase, then the connection attempt can begin.
238
239 Finally use the command-line tool ``curl`` to test whether the remote
240 host is ready to accept connections.  This command uses the ``-k``
241 option to allow insecure connections, so the certificate authority is
242 not required here::
243
244   curl -vk --cert acumos.pem:mykey123456 --key acumos.key https://yourserver.yourmodels.org:9084/ping
245
246
247 Template openssl.cnf
248 --------------------
249
250 ::
251
252   # This is a customized OpenSSL configuration file. Commented out sections below
253   # are included for testing/clarity for now, and will be removed later once the
254   # specific comments that need to be retained for clarity are determined.
255   #
256
257   # This definition stops the following lines choking if HOME isn't
258   # defined.
259   HOME                    = .
260   RANDFILE                = $ENV::HOME/.rnd
261
262   # Extra OBJECT IDENTIFIER info:
263   #oid_file               = $ENV::HOME/.oid
264   oid_section             = new_oids
265
266   # To use this configuration file with the "-extfile" option of the
267   # "openssl x509" utility, name here the section containing the
268   # X.509v3 extensions to use:
269   extensions            = v3_req
270   # (Alternatively, use a configuration file that has only
271   # X.509v3 extensions in its main [= default] section.)
272
273   [ new_oids ]
274
275   # We can add new OIDs in here for use by 'ca', 'req' and 'ts'.
276   # Add a simple OID like this:
277   # testoid1=1.2.3.4
278   # Or use config file substitution like this:
279   # testoid2=${testoid1}.5.6
280
281   # Policies used by the TSA examples.
282   tsa_policy1 = 1.2.3.4.1
283   tsa_policy2 = 1.2.3.4.5.6
284   tsa_policy3 = 1.2.3.4.5.7
285
286   ####################################################################
287   [ ca ]
288   default_ca      = CA_default            # The default ca section
289
290   ####################################################################
291   [ CA_default ]
292
293   dir             = .                     # Where everything is kept
294   certs           = $dir/certs            # Where the issued certs are kept
295   crl_dir         = $dir/crl              # Where the issued crl are kept
296   database        = $dir/index.txt        # database index file.
297   #unique_subject = no                    # Set to 'no' to allow creation of
298                                           # several ctificates with same subject.
299   new_certs_dir   = $dir/newcerts         # default place for new certs.
300
301   certificate     = $dir/certs/acumos_ca.crt     # The CA certificate
302   serial          = $dir/serial           # The current serial number
303   crlnumber       = $dir/crlnumber        # the current crl number
304                                           # must be commented out to leave a V1 CRL
305   crl             = $dir/crl.pem          # The current CRL
306   private_key     = $dir/private/acumos_ca.key   # The private key
307   RANDFILE        = $dir/private/.rand    # private random number file
308
309   x509_extensions = usr_cert              # The extentions to add to the cert
310
311   # Comment out the following two lines for the "traditional"
312   # (and highly broken) format.
313   name_opt        = ca_default            # Subject Name options
314   cert_opt        = ca_default            # Certificate field options
315
316   # Extension copying option: use with caution.
317   copy_extensions = copy
318
319   # Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
320   # so this is commented out by default to leave a V1 CRL.
321   # crlnumber must also be commented out to leave a V1 CRL.
322   # crl_extensions        = crl_ext
323
324   default_days    = 365                   # how long to certify for
325   default_crl_days= 30                    # how long before next CRL
326   default_md      = default               # use public key default MD
327   preserve        = no                    # keep passed DN ordering
328
329   # A few difference way of specifying how similar the request should look
330   # For type CA, the listed attributes must be the same, and the optional
331   # and supplied fields are just that :-)
332   policy          = policy_match
333
334   # For the CA policy
335   [ policy_match ]
336   countryName             = match
337   stateOrProvinceName     = match
338   organizationName        = match
339   organizationalUnitName  = optional
340   commonName              = supplied
341   emailAddress            = optional
342
343   # For the 'anything' policy
344   # At this point in time, you must list all acceptable 'object'
345   # types.
346   [ policy_anything ]
347   countryName             = optional
348   stateOrProvinceName     = optional
349   localityName            = optional
350   organizationName        = optional
351   organizationalUnitName  = optional
352   commonName              = supplied
353   emailAddress            = optional
354
355   ####################################################################
356   [ req ]
357   default_bits            = 2048
358   default_keyfile         = privkey.pem
359   distinguished_name      = req_distinguished_name
360   attributes              = req_attributes
361   x509_extensions = v3_ca # The extentions to add to the self signed cert
362
363   # Passwords for private keys if not present they will be prompted for
364   # input_password = secret
365   # output_password = secret
366
367   # This sets a mask for permitted string types. There are several options.
368   # default: PrintableString, T61String, BMPString.
369   # pkix   : PrintableString, BMPString (PKIX recommendation before 2004)
370   # utf8only: only UTF8Strings (PKIX recommendation after 2004).
371   # nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).
372   # MASK:XXXX a literal mask value.
373   # WARNING: ancient versions of Netscape crash on BMPStrings or UTF8Strings.
374   string_mask = utf8only
375
376   req_extensions = v3_req # The extensions to add to a certificate request
377
378   [ req_distinguished_name ]
379   countryName                     = Country Name (2 letter code)
380   countryName_default             = US
381   countryName_min                 = 2
382   countryName_max                 = 2
383
384   stateOrProvinceName             = State or Province Name (full name)
385   stateOrProvinceName_default     = Some-State
386
387   localityName                    = Locality Name (eg, city)
388
389   0.organizationName              = Organization Name (eg, company)
390   0.organizationName_default      = Internet Widgits Pty Ltd
391
392   # we can do this but it is not needed normally :-)
393   #1.organizationName             = Second Organization Name (eg, company)
394   #1.organizationName_default     = World Wide Web Pty Ltd
395
396   organizationalUnitName          = Organizational Unit Name (eg, section)
397   #organizationalUnitName_default =
398
399   commonName                      = Common Name (e.g. server FQDN or YOUR name)
400   commonName_max                  = 64
401
402   emailAddress                    = Email Address
403   emailAddress_max                = 64
404
405   # SET-ex3                       = SET extension number 3
406
407   [ req_attributes ]
408   challengePassword               = A challenge password
409   challengePassword_min           = 4
410   challengePassword_max           = 20
411
412   unstructuredName                = An optional company name
413
414   [ usr_cert ]
415
416   # These extensions are added when 'ca' signs a request.
417
418   # This goes against PKIX guidelines but some CAs do it and some software
419   # requires this to avoid interpreting an end user certificate as a CA.
420
421   basicConstraints=CA:FALSE
422
423   # Here are some examples of the usage of nsCertType. If it is omitted
424   # the certificate can be used for anything *except* object signing.
425
426   # This is OK for an SSL server.
427   # nsCertType                    = server
428
429   # For an object signing certificate this would be used.
430   # nsCertType = objsign
431
432   # For normal client use this is typical
433   # nsCertType = client, email
434
435   # and for everything including object signing:
436   # nsCertType = client, email, objsign
437
438   # This is typical in keyUsage for a client certificate.
439   # keyUsage = nonRepudiation, digitalSignature, keyEncipherment
440
441   # This will be displayed in Netscape's comment listbox.
442   nsComment                       = "OpenSSL Generated Certificate"
443
444   # PKIX recommendations harmless if included in all certificates.
445   subjectKeyIdentifier=hash
446   authorityKeyIdentifier=keyid,issuer
447
448   # This stuff is for subjectAltName and issuerAltname.
449   # Import the email address.
450   # subjectAltName=email:copy
451   # An alternative to produce certificates that aren't
452   # deprecated according to PKIX.
453   # subjectAltName=email:move
454
455   # Copy subject details
456   # issuerAltName=issuer:copy
457
458   #nsCaRevocationUrl              = http://www.domain.dom/ca-crl.pem
459   #nsBaseUrl
460   #nsRevocationUrl
461   #nsRenewalUrl
462   #nsCaPolicyUrl
463   #nsSslServerName
464
465   # This is required for TSA certificates.
466   # extendedKeyUsage = critical,timeStamping
467
468   [ v3_req ]
469
470   # Extensions to add to a certificate request
471
472   basicConstraints = CA:FALSE
473   keyUsage = nonRepudiation, digitalSignature, keyEncipherment
474   subjectAltName = @alt_names
475   # Included these for openssl x509 -req -extfile
476   subjectKeyIdentifier=hash
477   authorityKeyIdentifier=keyid,issuer
478
479   [ alt_names ]
480
481   DNS.1 = <acumos-host>
482   # federation-service: for portal-be access to federation local port via expose
483   DNS.2 = federation-service
484
485   [ v3_ca ]
486
487
488   # Extensions for a typical CA
489
490
491   # PKIX recommendation.
492
493   subjectKeyIdentifier=hash
494
495   authorityKeyIdentifier=keyid:always,issuer
496
497   # This is what PKIX recommends but some broken software chokes on critical
498   # extensions.
499   #basicConstraints = critical,CA:true
500   # So we do this instead.
501   basicConstraints = CA:true
502
503   # Key usage: this is typical for a CA certificate. However since it will
504   # prevent it being used as an test self-signed certificate it is best
505   # left out by default.
506   # keyUsage = cRLSign, keyCertSign
507
508   # Some might want this also
509   # nsCertType = sslCA, emailCA
510
511   # Include email address in subject alt name: another PKIX recommendation
512   # subjectAltName=email:copy
513   # Copy issuer details
514   # issuerAltName=issuer:copy
515
516   # DER hex encoding of an extension: beware experts only!
517   # obj=DER:02:03
518   # Where 'obj' is a standard or added object
519   # You can even override a supported extension:
520   # basicConstraints= critical, DER:30:03:01:01:FF
521
522   [ crl_ext ]
523
524   # CRL extensions.
525   # Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.
526
527   # issuerAltName=issuer:copy
528   authorityKeyIdentifier=keyid:always
529
530   [ proxy_cert_ext ]
531   # These extensions should be added when creating a proxy certificate
532
533   # This goes against PKIX guidelines but some CAs do it and some software
534   # requires this to avoid interpreting an end user certificate as a CA.
535
536   basicConstraints=CA:FALSE
537
538   # Here are some examples of the usage of nsCertType. If it is omitted
539   # the certificate can be used for anything *except* object signing.
540
541   # This is OK for an SSL server.
542   # nsCertType                    = server
543
544   # For an object signing certificate this would be used.
545   # nsCertType = objsign
546
547   # For normal client use this is typical
548   # nsCertType = client, email
549
550   # and for everything including object signing:
551   # nsCertType = client, email, objsign
552
553   # This is typical in keyUsage for a client certificate.
554   # keyUsage = nonRepudiation, digitalSignature, keyEncipherment
555
556   # This will be displayed in Netscape's comment listbox.
557   nsComment                       = "OpenSSL Generated Certificate"
558
559   # PKIX recommendations harmless if included in all certificates.
560   subjectKeyIdentifier=hash
561   authorityKeyIdentifier=keyid,issuer
562
563   # This stuff is for subjectAltName and issuerAltname.
564   # Import the email address.
565   # subjectAltName=email:copy
566   # An alternative to produce certificates that aren't
567   # deprecated according to PKIX.
568   # subjectAltName=email:move
569
570   # Copy subject details
571   # issuerAltName=issuer:copy
572
573   #nsCaRevocationUrl              = http://www.domain.dom/ca-crl.pem
574   #nsBaseUrl
575   #nsRevocationUrl
576   #nsRenewalUrl
577   #nsCaPolicyUrl
578   #nsSslServerName
579
580   # This really needs to be in place for it to be a proxy certificate.
581   proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:3,policy:foo
582
583   ####################################################################
584   [ tsa ]
585
586   default_tsa = tsa_config1       # the default TSA section
587
588   [ tsa_config1 ]
589
590   # These are used by the TSA reply generation only.
591   dir             = ./demoCA              # TSA root directory
592   serial          = $dir/tsaserial        # The current serial number (mandatory)
593   crypto_device   = builtin               # OpenSSL engine to use for signing
594   signer_cert     = $dir/tsacert.pem      # The TSA signing certificate
595                                           # (optional)
596   certs           = $dir/cacert.pem       # Certificate chain to include in reply
597                                           # (optional)
598   signer_key      = $dir/private/tsakey.pem # The TSA private key (optional)
599
600   default_policy  = tsa_policy1           # Policy if request did not specify it
601                                           # (optional)
602   other_policies  = tsa_policy2, tsa_policy3      # acceptable policies (optional)
603   digests         = md5, sha1             # Acceptable message digests (mandatory)
604   accuracy        = secs:1, millisecs:500, microsecs:100  # (optional)
605   clock_precision_digits  = 0     # number of digits after dot. (optional)
606   ordering                = yes   # Is ordering defined for timestamps?
607                                   # (optional, default: no)
608   tsa_name                = yes   # Must the TSA name be included in the reply?
609                                   # (optional, default: no)
610   ess_cert_id_chain       = no    # Must the ESS cert id chain be included?
611                                   # (optional, default: no