Using TLS Certificates
To secure communications with the services, the 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:
nonRepudiationdigitalSignaturekeyEncipherment
They should 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 two-factor authentication.
The certificates should contain the following keyUsage:
dataEnciphermentdigitalSignaturekeyEncipherment
They should also 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
In the present manual 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) | |
| app_ssl_cert: app_ssl_key: |
app.crt app.key |
app_hostname: | nonRepudiation digitalSignature keyEncipherment |
crt(pem) | |
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) | |
vds_master_ssl_cert: vds_master_ssl_key: |
vds_master.crt vds_master.key |
vds_master_hostname: | nonRepudiation digitalSignature keyEncipherment |
crt(pem) | |
vds_slave_ssl_cert: vds_slave_ssl_key: |
vds_slave.crt vds_slave.key |
vds_slave_hostname: | nonRepudiation digitalSignature keyEncipherment |
crt(pem) | 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 |
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. The CA.cert filename is mandatory. You cannot use any other names, such as CA.pem, and so on.
Solution 1: public trusted certificates
This approach is intended to use Public Certificate signed by a trusted Certificate Authority.
You need to obtain as many valid certificates as required, each of certificates should match to each of DNS names specified in config.yml.
The present solution cannot be implemented for the intermediate certificate(-s). In this case, you should use the solution 2 and place the entire certificate chain to certificate/CA.cert. Copy x509 Server-certs and x509 Client-certs files in PEM format to the certificates directory and edit the secrets.yml file to match the filenames before starting the installation.
You can generate a Certificate Sign Request (CSR) for each DNS hostname using the generate-certificates.sh routine.
Solution 2: entity trusted certificates
This approach is intended to use the Entity Trusted Certificates signed by a local intermediate Certificate Authority.
This solution is similar to Solution 1, the only difference is that you should place the entire certificate chain in PEM format to the certificate/CA.cert file.
Create and sign certificates in a preferred way, then copy the x509 Server-certs and x509 Client-certs files in PEM format to the certificates directory and edit the secrets.yml file to match the filenames before starting the installation.
You can use generate-certificates.sh to sign
all required certificates by Certificate Authority (here and bellow CA)
key or generate Certificates Sign Requests (here and bellow CSR) and
sign it manually.
Ensure, that you import the intermediate certificate to each component/workplace, which interacts with the WorkFusion platform. Refer to an example for a Microsoft Windows workplace in How-to Import Root or Intermidiate CA to Store.
Solution: 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.
Create openssl
caconf.cnf, save it to thecerts_dbfolder.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:alwaysDefine and provide the CA key password via the
PASSPHRASEenvironment variable.Export
PASSPHRASE=changeMePass.Create and sign the CA certificate.
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.keyGenerate 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.keyExample 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/Copy the CA certificate.
cp ./wfs_ca.crt ../certificates/CA.certDistribute the CA certificate.
Ensure, that you import the intermediate certificate to each component or workplace, which interacts with the WorkFusion platform. Refer to an example for a Microsoft Windows workplace in How-to Import Root or Intermidiate CA to Store.
Generate Vault certificates
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 the certificate and CSR generation routine. Onscreen help can be invoked by running generate-certificate.sh -h.
Configuration
generate-certificates.sh operates with config.yml and secrets.yml settings. Fill in these files before proceed. This is the last step. In case of changes, it is possible to regenerate certificates.
generate-certificates.sh can be used to generate Vault certificates. This does not require additional actions or setup.
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).
caution
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 a provided key.
Provide CA key password in a secure manner by setting the CA_KEYPASS_IN environment variable.
caution
Do not change certificates names or settings in config.yml and secret.yml.
Ensure, that you import the intermediate certificate to each component/workplace, which interacts with the WorkFusion platform. Refer to an example for a Microsoft Windows workplace in How-to Import Root or Intermidiate 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 certs_db folder, then start generate-certificates.sh again for sign by a provided key.
Provide CA key password is secure manner by setting the CA_KEYPASS_IN environment variable.
caution
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/workplace, which interacts with the WorkFusion platform. Refer to an example for a Microsoft Windows workplace in How-to Import Root or Intermidiate CA to Store.
Option 4. Self-signed certificates
This options should be used at your 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/workplace, which interacts with the WorkFusion platform. Refer to an example for a Microsoft Windows workplace in How-to Import Root or Intermidiate CA to Store.