At Verifalia, users can provide digital certificates compliant with the X.509 standards to the Verifalia servers to prove their identities, as part of the TLS protocol handshake: this process is known as client-certificate authentication (or mutual or two-way authentication). See also: what is X.509 TLS client-certificate authentication?
While it is possible to use client certificates signed by a public certificate authority (CA), organizations often set up a private certificate authority to issue certificates and Verifalia also accepts self-signed client certificates: issuing a self-signed client certificate requires certain technical skills, the ability to fully understand the used commands (e.g. openssl) and options, and requires to later store the generated keys in a safe place and protect them from unauthorized access.
Generating a CA root certificate
As the first step of the process, it is required to have a CA root certificate which vouches the validity of the client certificates we are going to generate. Here is a shell (bash) script (adapted from this gist) which will generate a new sample ca.key and ca.pem (respectively, the private key and the public certificate of the CA):
openssl genrsa -aes256 -passout pass:xxxx -out ca.pass.key 4096
openssl rsa -passin pass:xxxx -in ca.pass.key -out ca.key
rm ca.pass.key
openssl req -new -x509 -days 3650 -key ca.key -out ca.pem
When prompted, one can use whatever details to fill the root CA details.
Creating a self-signed client certificate
In the second, final step to generate a self-signed X.509 client certificate usable for mutual TLS-authentication, the root CA certificate is used to issue the final file, starting from a certificate request (CSR). Here is a sample shell script (bash) which will generate a new sample client.key, client.pem and client.full.pem (respectively, the private key of the client, the public client certificate and the full client certificate):
openssl genrsa -aes256 -passout pass:xxxx -out client.pass.key 4096
openssl rsa -passin pass:xxxx -in client.pass.key -out client.key
rm client.pass.key
openssl req -new -key client.key -out client.csr
openssl x509 -req -days 365 -in client.csr -CA ca.pem -CAkey ca.key \
-set_serial "01" -extfile <(printf "extendedKeyUsage=clientAuth") \
-out client.pem
cat client.key client.pem ca.pem > client.full.pem
Again, when prompted, one can use whatever details to fill the client certificate details.
Bind a client certificate to a user
Binding a client certificate to a Verifalia user requires uploading through the Verifalia client area the client.pem file, which is safe to share and does not contain the private key of the user.
One can bind the certificate through the Account -> Users interface, on the Authentication tab: once client certificate authentication is enabled, it is possible to add and remove the certificates for a user by following the Manage client certificates (X.509)... link shown in the aforementioned interface.
Invoking the API with the client certificate
Using the certificate to invoke the Verifalia API endpoints requires to use the client.full.pem (which includes the private key of the user); here is how to use it while calling the Verifalia API through cURL:
curl --cert client.full.pem https://api-cca.verifalia.com/...
In this case, do not forget to use the API endpoints which allow this kind of authentication mechanism, which are the ones beginning with the api-cca* host name.
For sample usages with the Verifalia SDKs please see our developers reference.