Edit

TLS certificates

To secure communications with the services, WorkFusion platform uses several x509 certificates. In the current version only few services are TLS enabled, but it is enough to secure most of the traffic.

Current concept

There are three types of the certificates used during setup. They can be grouped according to their functions.

The first group is the web server certificates (below Server-certs), which are used to encrypt communications with the frontend and the end user.

The certificates should contain the following keyUsage:

• nonRepudiation
• digitalSignature
• keyEncipherment

and strictly match to DNS in common name or SAN (Subject Alternative Name).

The second group is the TLS client certificates (below Client-certs), which are used during the 2 way authentication.

The certificates should contain the following keyUsage:

• dataEncipherment
• digitalSignature
• keyEncipherment

and strictly match to DNS in common name or SAN (Subject Alternative Name).

The third group is the Vault related certificates.

Although, there are no restrictions implied to the use of the self-signed certificates for Vault presently, the approach will be changed in future releases.

Hostnames

It is assumed that the certificates common names match to dns hostnames as defined in config.yml.

certificate/key name (secret.yml)	default file names	hostname variable (config.yml)	key usage	certificate format	note
apm_ssl_cert apm_ssl_key	apm.crt apm.key	apm_hostname:	nonRepudiation digitalSignature keyEncipherment	crt(pem)	Include end certificate plus intermediate(s).
app_ssl_cert: app_ssl_key:	app.crt app.key	app_hostname:	nonRepudiation digitalSignature keyEncipherment	crt(pem)	Include end certificate plus intermediate(s).
db_ssl_cert: db_ssl_key:	db.crt db.key	db_hostname:	nonRepudiation digitalSignature keyEncipherment	crt(pem)	should include a wildcard to 3th level domain, for example, *.db_hostname domain
ocr_ssl_cert: ocr_ssl_key:	ocr.crt ocr.key	ocr_hostname:	nonRepudiation digitalSignature keyEncipherment	crt(pem)	Include end certificate plus intermediate(s).
vds_master_ssl_cert: vds_master_ssl_key:	vds_master.crt vds_master.key	vds_master_hostname:	nonRepudiation digitalSignature keyEncipherment	crt(pem)	Include end certificate plus intermediate(s).
vds_slave_ssl_cert: vds_slave_ssl_key:	vds_slave.crt vds_slave.key	vds_slave_hostname:	nonRepudiation digitalSignature keyEncipherment	crt(pem)	Include end certificate plus intermediate(s). wildcard can be used.
		app_hostname:	nonRepudiation digitalSignature keyEncipherment	crt(pem)
vault_admin_cert_file:	vault_admin.p12			p12
vault_workfusion_cert_file:	vault_workfusion.p12			p12
vault_sandbox_cert_file:	vault_sandbox.p12			p12
vault_host_cert_file:	vault_host.p12			p12
	CA.cert			crt(pem)	intermediate/selfSign certificate. Include ONLY ROOT certificate

caution

Double-check that your CA file is placed into the certificates directory and named as CA.cert before you start the installation, as it can produce errors with the java trust store later. CA.cert filename is mandatory! You cannot use any other names, such as CA.pem, etc.

Solution 1: Trusted certificates

This approach is intended to use the Trusted Certificates signed by trusted intermediate CA or directly by ROOT CA. For self-signed certificates see Solution 2.

For versions 8.5+ prior to Installer Version 9.0.0.7, you should place the entire certificate chain in PEM format to the certificate/CA.cert file.

Since Installer Version 9.0.0.8, the procedure for preparing the TLS certificates has changed:

• CA.cert must contain only ROOT certificate
• application certificates(db,app,apm,ocr,vds_master,vds_slave) must contain end certificate in first place and then all intermediate certificates if they are exist to complete chain with ROOT certificate

EXAMPLE wilcard certificate with intermediate CA for Installer Version 9.0.0.8+

Let assume that you need to setup SSL for hostnames *.example.com, you already defined hostnames in config.yml:

• apm_hostname: apm.example.com
• db_hostname: db.example.com
• app_hostname: app.example.com
• ocr_hostname: ocr.example.com
• vds_master_hostname: vds-master.example.com
• vds_slave_hostname: vds-slave.example.com

You got next certificates from your SSL provider:

• ca.cer contains ROOT CA certificate.
• intermediate.cer contains intermediate certificate signed by ROOT CA certificate.
• domain.cer is a wildcard certificate for *.example.com.
• domain.key contains private key for domain.cer.

Required actions:

1. Concatenate intermediate.cer and domain.cer into the one file.

   cat domain.cer intermediate.cer > fullchain.cer
   

   caution

   Order does matter. Content of the domain.cer file must be on top of resulting fullchain.cer.

2. Copy certificates to the installation folder:

   cp ca.cer certificates/CA.cert
   
   cp fullchain.cer certificates/db.crt
   cp domain.key certificates/db.key
   
   cp fullchain.cer certificates/app.crt
   cp domain.key certificates/app.key
   
   cp fullchain.cer certificates/apm.crt
   cp domain.key certificates/apm.key
   
   cp fullchain.cer certificates/ocr.crt
   cp domain.key certificates/ocr.key
   
   cp fullchain.cer certificates/vds-master.crt
   cp domain.key certificates/vds-master.key
   
   cp fullchain.cer certificates/vds-slave.crt
   cp domain.key certificates/vds-slave.key
   

3. Generate VAULT certificates using the procedure described below.

EXAMPLE wilcard certificate without intermediate CA for Installer Version 9.0.0.8+

Let assume that you need to setup SSL for hostnames *.example.com, you already defined hostnames in config.yml:

• apm_hostname: apm.example.com
• db_hostname: db.example.com
• app_hostname: app.example.com
• ocr_hostname: ocr.example.com
• vds_master_hostname: vds-master.example.com
• vds_slave_hostname: vds-slave.example.com

You got next certificates from your SSL provider:

• ca.cer contains ROOT CA certificate.
• domain.cer is a wildcard certificate for *.example.com signed by ROOT CA certificate.
• domain.key contains private key for domain.cer.

Required actions:

1. Copy certificates to the installation folder:

   cp ca.cer certificates/CA.cert
   
   cp domain.cer certificates/db.crt
   cp domain.key certificates/db.key
   
   cp domain.cer certificates/app.crt
   cp domain.key certificates/app.key
   
   cp domain.cer certificates/apm.crt
   cp domain.key certificates/apm.key
   
   cp domain.cer certificates/ocr.crt
   cp domain.key certificates/ocr.key
   
   cp domain.cer certificates/vds-master.crt
   cp domain.key certificates/vds-master.key
   
   cp domain.cer certificates/vds-slave.crt
   cp domain.key certificates/vds-slave.key
   

2. Generate VAULT certificates using the procedure described below.

Solution 2: Self-signed certificates

This approach is intended to use the Self Signed Certificates signed by an untrusted CA, for example, self signed Certificate Authority.

Certificates can be generated by generate-certificates.sh or manually.

In this case, you create your own PKI solution and sign the certificates there.

1. Create openssl caconf.cnf, save it to the certs_db folder.

   certs_db/caconf.cnf:

   # This definition stops the following lines choking if HOME isn't
   # defined.
   HOME                    = .
   RANDFILE                = $ENV::HOME/.rnd
   
   # Extra OBJECT IDENTIFIER info:
   #oid_file               = $ENV::HOME/.oid
   oid_section             = new_oids
   
   # To use this configuration file with the "-extfile" option of the
   # "openssl x509" utility, name here the section containing the
   # X.509v3 extensions to use:
   # extensions            =
   # (Alternatively, use a configuration file that has only
   # X.509v3 extensions in its main [= default] section.)
   
   [ new_oids ]
   
   # We can add new OIDs in here for use by 'ca', 'req' and 'ts'.
   # Add a simple OID like this:
   # testoid1=1.2.3.4
   # Or use config file substitution like this:
   # testoid2=${testoid1}.5.6
   
   # Policies used by the TSA examples.
   tsa_policy1 = 1.2.3.4.1
   tsa_policy2 = 1.2.3.4.5.6
   tsa_policy3 = 1.2.3.4.5.7
   
   ####################################################################
   [ ca ]
   default_ca      = CA_wfs_ca
   
   ####################################################################
   [ CA_wfs_ca ]
   
   dir                             = /Data/WFP/Installer/develop/flat/installer/certs_db
   certs                       = $dir/
   crl_dir                     = $dir/crl
   database                    = $dir/index.txt
   new_certs_dir           = /Data/WFP/Installer/develop/flat/installer/certs_db
   certificate                 = $dir/wfs_ca.crt
   private_key                 = $dir/wfs_ca.key
   RANDFILE                    = $dir/private/.rand
   serial                      = $dir/serial
   crlnumber                   = $dir/crlnumber
   crl                             = $dir/crl.pem
   x509_extensions         = usr_cert
   
   # Comment out the following two lines for the "traditional"
   # (and highly broken) format.
   name_opt                    = ca_default                # Subject Name options
   cert_opt                    = ca_default                # Certificate field options
   
   # Extension copying option: use with caution.
   # copy_extensions = copy
   
   # Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
   # so this is commented out by default to leave a V1 CRL.
   # crlnumber must also be commented out to leave a V1 CRL.
   # crl_extensions        = crl_ext
   
   default_days            = 3650                  # how long to certify for
   default_crl_days        = 30                    # how long before next CRL
   default_md                  = default           # use public key default MD
   preserve                    = no                        # keep passed DN ordering
   
   # A few difference way of specifying how similar the request should look
   # For type CA, the listed attributes must be the same, and the optional
   # and supplied fields are just that :-)
   policy                      = policy_match
   email_in_dn             = no                    # Don't add the email into cert DN
   
   # For the CA policy
   [ policy_match ]
   countryName                     = match
   stateOrProvinceName         = match
   organizationName            = match
   organizationalUnitName  = optional
   commonName                      = supplied
   emailAddress                = supplied
   
   # For the 'anything' policy
   # At this point in time, you must list all acceptable 'object'
   # types.
   [ policy_anything ]
   countryName                     = optional
   stateOrProvinceName         = optional
   localityName                = optional
   organizationName            = optional
   organizationalUnitName  = optional
   commonName                      = supplied
   emailAddress                = optional
   
   ####################################################################
   [ req ]
   default_bits            = 4096
   default_keyfile         = privkey.pem
   default_md          = sha512
   distinguished_name      = req_distinguished_name
   attributes                  = req_attributes
   x509_extensions     = req_ssign_ca      # The extensions to add to the self signed cert
   req_extensions      = req_ca
   # This sets a mask for permitted string types. There are several options.
   # default: PrintableString, T61String, BMPString.
   # pkix   : PrintableString, BMPString (PKIX recommendation before 2004)
   # utf8only: only UTF8Strings (PKIX recommendation after 2004).
   # nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).
   # MASK:XXXX a literal mask value.
   # WARNING: ancient versions of Netscape crash on BMPStrings or UTF8Strings.
   string_mask         = MASK:0x2002
   
   ####################################################################
   [ req_distinguished_name ]
   countryName                             = Country Name (2 letter code)
   countryName_default                 = US
   countryName_min                     = 2
   countryName_max                     = 2
   
   stateOrProvinceName                 = State or Province Name (full name)
   stateOrProvinceName_default     = NY
   
   localityName                        = Locality Name (eg, city)
   localityName_default        = NY
   
   0.organizationName                  = Organization Name (eg, company)
   0.organizationName_default      = workfusion
   
   organizationalUnitName          = Organizational Unit Name (eg, section)
   organizationalUnitName_default  = ops
   
   commonName                              = Common Name (e.g. server FQDN or YOUR name)
   commonName_max                      = 64
   
   emailAddress                        = Email Address
   emailAddress_max                    = 64
   emailAddress_default        = ops@workfusion.com
   
   [ req_attributes ]
   challengePassword                   = A challenge password
   challengePassword_min           = 4
   challengePassword_max           = 20
   
   unstructuredName                    = An optional company name
   
   [ req_ca ]
   # Extensions for a typical CA
   # PKIX recommendation.
   basicConstraints       = critical,CA:true,pathlen:0
   subjectKeyIdentifier   = hash
   # authorityKeyIdentifier = keyid:always,issuer:always
   # authorityKeyIdentifier = keyid,issuer
   keyUsage               = cRLSign, keyCertSign
   nsCertType             = sslCA
   
   [ req_ssign_ca ]
   # Extensions for a typical CA
   # PKIX recommendation.
   basicConstraints       = critical,CA:true,pathlen:0
   subjectKeyIdentifier   = hash
   # authorityKeyIdentifier = keyid:always,issuer:always
   # authorityKeyIdentifier = keyid,issuer
   keyUsage               = cRLSign, keyCertSign
   nsCertType             = sslCA
   
   [ req_server ]
   # Extensions to add to a certificate request
   basicConstraints     = critical,CA:false
   keyUsage             = nonRepudiation, digitalSignature, keyEncipherment
   subjectKeyIdentifier = hash
   subjectAltName       = $ENV::ALTNAME
   nsCertType           = server
   
   [ req_client ]
   # Extensions to add to a certificate request
   basicConstraints     = critical,CA:false
   keyUsage             = dataEncipherment, digitalSignature, keyEncipherment
   subjectKeyIdentifier = hash
   subjectAltName       = $ENV::ALTNAME
   nsCertType           = client, email
   
   [ crl_ext ]
   # CRL extensions.
   # Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.
   # issuerAltName=issuer:copy
   authorityKeyIdentifier=keyid:always
   

   1. Define and provide CA key password via the PASSPHRASE environment variable.

   2. Export PASSPHRASE=changeMePass.

   3. Create and sign the CA certificate.

2. Generate the self-signed CA certificate. Make sure that permissions are set to reasonable defaults.

   openssl req -new -x509 -days 3650 -extensions req_ssign_ca -reqexts req_ssign_ca\
       -out wfs_ca.crt -key wfs_ca.key \
       -subj "/C=Country_Name/ST=State_Name/O=Org_Name/localityName=Locality_Name/commonName=CAcert/organizationalUnitName=OrgUnitName" \ 
       -passin env:PASSPHRASE -config certs_db/caconf.cnf
   
   chmod 0644 wfs_ca.crt
   chmod 0400 wfs_ca.key
   

3. Generate and sign the Server-certificate Requests.

   Repeat the procedure for each hostname defined.

   Example for db-server with hostname db.mydomain.com:

   openssl req -new -days 365 -out db.crt.csr -keyout db.key -nodes -config ./caconf.cnf\
       -subj "/C=Country_Name/ST=State_Name/O=Org_Name/localityName=Locality_Name/commonName=*.db.mydomain.com/organizationalUnitName=OrgUnitName/emailAddress=ops@mydomain.com"\
       -reqexts req_server
   openssl x509 -req -in db.crt.csr -out db.crt -days 365 -CA ./wfs_ca.crt -CAkey ./wfs_ca.key\
       -CAcreateserial -passin env:PASSPHRASE -extensions req_server -extfile ./caconf.cnf
   chmod 0644 db.crt
   chmod 0644 db.key
   

   Example for app-server with hostname app.mydomain.com:

   openssl req -new -days 365 -out app.crt.csr -keyout app.key -nodes -config ./caconf.cnf\
       -subj "/C=Country_Name/ST=State_Name/O=Org_Name/localityName=Locality_Name/commonName=*.app.mydomain.com/organizationalUnitName=OrgUnitName/emailAddress=ops@mydomain.com"\
       -reqexts req_server
   openssl x509 -req -in app.crt.csr -out app.crt -days 365 -CA ./wfs_ca.crt -CAkey ./wfs_ca.key\
       -CAcreateserial -passin env:PASSPHRASE -extensions req_server -extfile ./caconf.cnf
   chmod 0644 app.crt
   chmod 0644 app.key
   
   
   cp ./app.crt  ../certificates/
   cp ./app.crt.csr  ../certificates/
   cp ./app.key  ../certificates/
   

4. Copy the CA certificate.

   cp ./wfs_ca.crt ../certificates/CA.cert          
   

5. Distribute the CA certificate.

   Ensure that you import the intermediate certificate to each component and workplace that interacts with the WorkFusion platform. Refer to an example for a Microsoft Windows workplace in Import Root or Intermediate CA to Store.

Generate Vault certificates manually

To start Vault it is necessary to provide four certificate/key pairs in P12 format.

Certificates can be generated by generate-certificates.sh.

Copy x509 Server-certs and x509 Client-certs files in P12 format to the certificates directory and edit the secrets.yml file to match the file names before starting installation.

The examples below assume that the pass is specified in the command line. Execute them in the certs_db directory.

vault_host

openssl req -new -x509 -days 3650 -out vault_host.cert -keyout vault_host.key -passout pass:vault_cert_host_passwd -subj /C=US/ST=NY/O=workfusion/localityName=NU/commonName=host/organizationalUnitName=ops/
openssl pkcs12 -export -in vault_host.cert -inkey vault_host.key -out vault_host.p12 -passin pass:vault_cert_host_passwd -password pass:vault_cert_host_passwd

vault_admin

openssl req -new -x509 -days 3650 -out vault_admin.cert -keyout vault_admin.key -passout pass:vault_adm_cert_vault_passwd -subj /C=US/ST=NY/O=workfusion/localityName=NU/commonName=admin/organizationalUnitName=ops/
openssl pkcs12 -export -in vault_admin.cert -inkey vault_admin.key -out vault_admin.p12 -passin pass:vault_adm_cert_vault_passwd -password pass:vault_adm_cert_vault_passwd

vault_workfusion

openssl req -new -x509 -days 3650 -out vault_workfusion.cert -keyout vault_workfusion.key -passout pass:vault_cert_wfvault_passwd -subj /C=US/ST=NY/O=workfusion/localityName=NU/commonName=workfusion/organizationalUnitName=ops/
openssl pkcs12 -export -in vault_workfusion.cert -inkey vault_workfusion.key -out vault_workfusion.p12 -passin pass:vault_cert_wfvault_passwd -password pass:vault_cert_wfvault_passwd

vault_sandbox

openssl req -new -x509 -days 3650 -out vault_sandbox.cert -keyout vault_sandbox.key -passout pass:vault_cert_wfsndboxvault_passwd -subj /C=US/ST=NY/O=workfusion/localityName=NU/commonName=sandbox/organizationalUnitName=ops/
openssl pkcs12 -export -in vault_sandbox.cert -inkey vault_sandbox.key -out vault_sandbox.p12 -passin pass:vault_cert_wfsndboxvault_passwd -password pass:vault_cert_wfsndboxvault_passwd

copy certificates

cp ./vault_*.p12 ../certificates/

generate-certificates.sh

generate-certificates.sh can be used to simplify certificate and CSR generation routine. Onscreen help can be invoked running generate-certificate.sh -h.

generate-certificates.sh operates with config.yml and secrets.yml settings. Fill in this files before you proceed. This is very last step in case of changes it possible to regenerate certificates. generate-certificates.sh can be used to generate vault certificates. This does not require additional actions or setups.

Option 1. Entity trusted certificates, each signed via existed PKI

It possible to generate CSR and sign them via existed PKI. For CSR generation, fill filenames in secret.yml and provide correct dns names in config.yml.

Start generate-certificates.sh and follow the prompt then select YES for Omit creating a certificate sign request. Provide correct values after execution

CSR files named as certificate files witch are defined at secrets.yml will be located in certificates/, key files are located in the same location. Sing requests by PKI and replace existed CRT files with signed by your CA. CA.crt should be changed to signer certificate (or chain if it is).

warning

Do not change certificates names or settings in config.yml and secret.yml.

Option 2. Entity trusted certificates, signed via existed Intermediate Certificate

It possible to sign certificates via existed Intermediate CA. For certificate generation, fill filenames in secret.yml and provide correct dns names in config.yml.

Start generate-certificates.sh and follow the prompt then select NO for Omit creating a certificate sign request, follow onscreen instructions and store intermediate certificate and key in the certs_db/ folder then start generate-certificates.sh again for sign by the provided key. Provide CA key password is secure manner by setting the CA_KEYPASS_IN environment variable.

warning

Do not change certificates names or settings in config.yml and secret.yml.

Ensure that you import the intermediate certificate to each component and workplace that interacts with the WorkFusion platform. Refer to an example for a Microsoft Windows workplace in Import Root or Intermediate CA to Store.

Option 3. Entity trusted certificates, signed via new intermediate certificate sign request to existed PKI

It possible to sign certificates via existed Intermediate CA. For certificate generation fill filenames in secret.yml and provide correct dns names in config.yml

Start generate-certificates.sh and follow the prompt then select NO for Omit creating a certificate sign request, follow onscreen instructions, sing certificate sign requested by existed PKI and store intermediate certificate in the certs_db/ folder, then start generate-certificates.sh again for sign by provided key. Provide CA key password is secure manner by setting the CA_KEYPASS_IN environment variable

warning

Do not change certificates names or settings in config.yml and secret.yml.

You should manually append certificates/CA.cert with the signer certificate or signer certificate chain. Watch the certificate order. Ensure that you import the intermediate certificate to each component and workplace that interacts with the WorkFusion platform. Refer to an example for a Microsoft Windows workplace in Import Root or Intermediate CA to Store.

Option 4. Self-signed certificates

These options should be used by you own risk.

Start generate-certificates.sh and follow the prompt then select YES for Omit creating a certificate sign request.

Ensure that you import the intermediate certificate to each component and workplace that interacts with the WorkFusion platform. Refer to an example for a Microsoft Windows workplace in Import Root or Intermediate CA to Store.