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