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)