Obtaining a Client TLS Certificate

Overview

To be able to access Freja service points you need to obtain a client SSL/TLS certificate. A client certificate authenticates your application when it tries to communicate with Freja services. Additionally, Freja uses your Client certificate to identify you in its system when you try to send an authentication or signing request. Separate certificates are needed to access the Testing Environment and the Production Environment.

The following section provides you with instructions on how to generate an SSL/TLS key and a certificate signing request (CSR), which you can then send to Freja partner support to provide you with a client certificate. It also documents how to create a PKCS#12 file.

What is an SSL/TLS key and what is it used for?

The SSL/TLS key is a part of the Public Key Infrastructure (PKI) that is generally used in case of SSL/TLS certificates. A Public Key Infrastructure assumes asymmetric encryption, where two types of keys are used: a Private Key and a Public Key (included in an SSL/TLS certificate). The private key is based on the RSA algorithm and is used for authentication and the establishment of an SSL/TLS session.

Since encrypted data transmission takes too much time in case of asymmetric encryption, this kind of encryption is only used for a secure exchange of the symmetric key, which is used for actual transmitted data encryption and decryption.

What is a certificate signing request (CSR)?

A certificate signing request (also CSR or certification request) is a block of encoded text that is given to a certificate authority (CA) when applying for an SSL/TLS certificate. It is usually generated on the server where the certificate will be installed on and contains information that will be included in the certificate, such as the organisation name, common name (domain name), locality and country. It also contains the public key that will be included in the certificate. The private key is usually created at the same time as the CSR, thus making a key pair. 

A CSR is generally encoded using ASN.1, according to the PKCS #10 specification. Distinguished names SSL/TLS certificates contain identifying information, such as the qualified domain name used for DNS lookups of your server (also called Common Name), your organisation or company name and location information. This information is packaged in an information structured called Distinguished Name (DN) and is called the Subject DN. A similar structure represents information about the issuer, in that case known as Issuer DN. 

When generating a CSR on your server for the purposes of connecting to Freja, you are asked to enter the Subject DN, which uniquely identifies your application and/or organisation.

Below is an example list of required fields and their respective values for the Subject DN used when generating a CSR request for a Freja Relying Party named "ACME AB".

Generating a CSR - Step-by-step Guide

1. Launch Open SSL (preferably on the production server) and generate your private key with the genrsa command (see below). Command arguments are the location and file name where you wish to store your key and the key strength (with the minimum value of 2048 bits). You will also be prompted to choose a secure passphrase for the key.

2. You need to create an openssl config file named freja_openssl.conf. Depending on the version of openssl that you are using, you should create the file with the following content (make sure that the CN, OU, O, OID and C values reflect your organisation):
   
   For version of openssl 1.1.1f and later:

   [ req ] default_bits = 2048 prompt = no encrypt_key = no default_md = sha256 distinguished_name = dn [ dn ] CN = Document signing service OU = Production O = ACME AB C = SE organizationIdentifier = XXYYZZ-AABB

   
   For version of openssl older than 1.1.1f:

   oid_section = OIDs [ req ] default_bits = 2048 prompt = no encrypt_key = no default_md = sha2 distinguished_name = dn [ OIDs ] organizationIdentifier = 2.5.4.97 [ dn ] CN = Document signing service OU = Production O = ACME AB C = SE organizationIdentifier = XXYYZZ-AABB

3. Generate the CSR using the key generated in step 1 with the following command and put it in a file.

4. Compress the file with ZIP/gZIP and email it to partnersupport@frejaeid.com. After the certificate is issued by Freja eID Support, you will receive a ZIP file with your new certificate, along with required Freja eID CA certificates. The content of the ZIP file will be the following:

5. Generate the PKCS#12 keystore file with the following command and choose a secure passphrase:

6. Verify connectivity against production Freja services with the following command: