NOTE! This project is not active anymore, therefore marked as ARCHIVED; if you're interested to become the maintener of this project, open an issue or email help@finos.org .

Certificate Toolbox

A collection of command-line tools to generate PKI Signing Certificates and X.509 Identity Certificates used to configure a Symphony Pod and generate Service Account (cert-based) credentials.

How (cert-based) Service Account authentication works

A Service Account can interact with a Symphony Pod by using a set of API endpoints (ie https://foundation-dev-api.symphony.com/*), that must be configured (using Admin Console UI) to grant/deny access to the platform.

Using the Manage Certificates dashboard, you can import one or more "PKI signing certificates" (see how to generate it below)

When a Service Account wants to authenticate against the Agent API endpoint, it needs to provide an X.509 Identity Certificate (see how to generate it below); authentication is granted if:

• The Certificate Common Name (CN) starts with CN=<Service Account Username>
• The Certificate is signed with one of the "PKI signing certificates" configured on the Agent API endpoint

Read the official Symphony documentation to know more about this topic.

Generating certificates

Before moving forward, make sure you have OpenSSL installed on your command-line; type openssl to verify.

If not installed, choose your preferred package system to install it, otherwise check the openssl wiki third-party binaries

The following scripts will generate the signing and user certificates; the default duration of the certificates is 10 years (3650 days), but it can be overridden simply running the following command before starting:

export DURATION_IN_DAYS=14

This command will set the duration to 2 weeks (14 days).

Generating a PKI (Root CA) Signing Certificate

Simply run the script and follow the instructions

$ ./create-root-ca-cert.sh

The generated PKI signing certificate can be found in root/ca_signing_cert.pem and is ready to be imported via the Symphony Pod Admin Console; the certs folder will include a serial file to increment the IDs used to store the certificates.

If you need to re-run the script, you must either

1. delete the ./root folder (the scripts won't allow you to override them)
2. move (and backup) ./root and ./certs folders and rerun the script; if you are interested to generate multiple Root CA Certificates, check how to configure OpenSSL default values (below)

Generating a X.509 (User) Identity Certificate

Before starting, you must be aware that all User Certificates generated by the script are signed with the Root CA Certificate contained in the ./root folder; as such, you must run ./create-root-ca-cert.sh before running this script.

Simply run the script and follow the instructions

$ ./create-user-cert.sh <Service Account Username>

The script will generate the following files in the ./user folder:

• user/<Service Account Username>-cert.p12 - X.509 User Identity Certificate; password is the one passed to the script
• user/<Service Account Username>-key.pem - RSA Key; password is not set; check below in the common commands how change it
• user/<Service Account Username>-cert.pem

The certs folder

The first time you run the create-user-cert.sh script, a certs folder is created in the project root, which contains:

• A serial file, defining an incremental ID to assign to User Certificates; the first one is 100000
• a certindex.txt file, containing a summary of all the User Certificates generated (and their IDs)

Make sure you backup and keep this folder private.

OpenSSL configuration

To speed things up when generating the certificates, you can change the OpenSSL default configurations that are prompted by each script; however, we advise you to keep the other configurations as they are, unless you know what you're doing.

openssl-root-ca.ini

60: commonName_default = Symphony Bot Signing Certificate
61: 0.organizationName_default = My Company, Inc.
62: organizationalUnitName_default =
63: emailAddress_default =
64: localityName_default = NY
65: stateOrProvinceName_default = NY
66: countryName_default = US

openssl-user.ini

77: commonName_default = Symphony Bot User Identity Certificate
78: 0.organizationName_default = My Company, Inc.
79: organizationalUnitName_default =
80: emailAddress_default =
81: localityName_default = NY
82: stateOrProvinceName_default = NY
83: countryName_default = US

Common commands

Below is a collection of useful commands that I happened to need often when dealing with certificates.

Setup password to private key

openssl rsa -in user/<file-name>.pem -out user/<file-name>-new.pem -des3

Validate a PKCS12 password

openssl pkcs12 -info -in <file-name>.p12

Change a PKCS12 password

# Create a password-less certificate
openssl pkcs12 -in $FILE_NAME -out $FILE_NAME-pwdfree -nodes

# Set a new password
openssl pkcs12 -export -in $FILE_NAME-pwdfree -out $FILE_NAME-new

# Delete old certificate file
rm -f $FILE_NAME $FILE_NAME-pwdfree

# Restore certificate file name
mv $FILE_NAME-new $FILE_NAME

Contributing

1. Fork it (https://github.com/yourname/yourproject/fork)
2. Create your feature branch (git checkout -b feature/fooBar)
3. Read our contribution guidelines and Community Code of Conduct
4. Commit your changes (git commit -am 'Add some fooBar')
5. Push to the branch (git push origin feature/fooBar)
6. Create a new Pull Request

NOTE: Commits and pull requests to FINOS repositories will only be accepted from those contributors with an active, executed Individual Contributor License Agreement (ICLA) with FINOS OR who are covered under an existing and active Corporate Contribution License Agreement (CCLA) executed with FINOS. Commits from individuals not covered under an ICLA or CCLA will be flagged and blocked by the FINOS Clabot tool. Please note that some CCLAs require individuals/employees to be explicitly named on the CCLA.

Need an ICLA? Unsure if you are covered under an existing CCLA? Email help@finos.org

License

Copyright FINOS - 2019

Distributed under the Apache License, Version 2.0.

SPDX-License-Identifier: Apache-2.0