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