FSB-COMPLIANT KEYS AND CERTIFICATES MANAGEMENT: PRACTICAL GUIDELINES

2

Contents1. Context and objectives 3

2. Procedure and tools 42.1. WORKSTATION PREPARATION: INSTALL OPEN SSL AND KEYSTORE EXPLORER 42.1.1. OpenSSL for Windows 42.1.2. OpenSSL for Linux 42.1.3. Keystore explorer installation 5

2.2. GENERATE THE CSR 6

2.3. SEND CSR TO FSB TEAM 8

2.4. RETRIEVE THE CERTIFICATE AND LINK IT TO YOUR PRIVATE KEY 8

2.5. CREATING A NEW KEYSTORE 9

2.6. STORE THE KEY PAIR AND ALL NECESSARY CERTIFICATES INTO THE JKS 10

2.7. PERFORM AN AND TO END TEST 13

2.8. WORKING WITH AN EXISTING KEYSTORE 14

FSB-compliant keys and certificates management: practical guidelines

3

1. Context and objectivesIn order to meet the required level of security, the Federal Service Bus (FSB), amongst other things, requires its consumers to sign their messages Signing message requires using public-private key pairs and associated certificates. Managing this technical layer is the responsibility of the consumer. Since keys and certificates are in used in many IT domains, they usually have directives, procedures and tools in place to manage this. However, (1°) sometimes these directives, procedures and tools may not be designed to encompass message signing, and (2°) even if they do, they may fail to support some FSB-specific detailed specifications.Consequently, the FSB team decided to produce the current document. It provides practical instructions how to:

1. Prepare a workstation (install open ssl)2. generate an fsb-compliant key pair and a certificate signing request (CSR)3. send the CSR to the FSB team for production of the ad-hoc certificate4. once you have received the certificate, link it to the private key5. create an java Keystore (JKS)6. properly store the key pair and all necessary certificates into the JKS7. perform an end-to-end test

Remarks:- The target audience of this document are (a) the technical operators in charge of the management of

keys, (b) the operators in charge of running the application servers, and (c) their managers. They are supposed to know the prinicples of public and private keys and to be experienced with the use of the related technology.

- This document provides practical instructions how to proceed, based on existing freeware tools. It must be understood as purely informative. It is the responsibility of the service consumer team to decide to follow them strictly, to adapt them, or to meet other practices.

- We assume that the service consumer is a java application. In other situations, several aspects of the process may need to be altered (eg other keystore format).

- Users of this document are invited to send questions, issue remarks and improvement suggestions to this document.

FSB-compliant keys and certificates management: practical guidelines

4

2. Procedure and tools

2.1. WORKSTATION PREPARATION: INSTALL OPEN SSL AND KEYSTORE EXPLORER

2.1.1. OpenSSL for WindowsGo to http://slproweb.com/products/Win32OpenSSL.html

1. Download the release relative to your machine configuration. Run the installer and accept default settings.

Remarks:a. In some case you could get an error message when running the installer regarding a missing

Visual C++ component.You can get it from here : http://www.microsoft.com/en-us/download/details.aspx?id=29

b. further instructions assume OpenSSL is installed in C:\OpenSSL.2. Add C:\OpenSSL\bin to your system path (Control Panel, System, Advanced, Environment Variables,

System Variables) - this isn't strictly necessary but it makes things a lot easier.3. Create a working directory - here, we will use c:\ssl as our working folder.

FSB-compliant keys and certificates management: practical guidelines

5

2.1.2. OpenSSL for LinuxOpen SSL is shipped with most LINUX distributions Open SSL.

2.1.3. Keystore explorer installation Go to http://keystore-explorer.sourceforge.net and download the right version for your platform.

Install the tool. Follow the screen, no special configuration needed.

FSB-compliant keys and certificates management: practical guidelines

6

2.2. GENERATE THE CSR To generate the OpenSSL command, go to the following web site:

https://pkiwidgets.quovadisglobal.com/scriptgen/openssl.aspx

The “open SSL Command Tool” option tool simplifies the generation of a valid CSR. o Fill in the different fields according to your configuration and then press the “Generate Command”

button.o Important:

Serialnumber and other OU’s will be filed in later on QuoVadis website

o Example screenshot:

FSB-compliant keys and certificates management: practical guidelines

7

The tool returns following result:

click “Download Config File”. Save the file in your working directory (filename used in current example: yourCN.txt)Keep the browser open. open a command prompt.

Go to your working directory (c:\ssl) - where you previously saved the configuration file ( YourCN.txt ).

Edit the file. Replace default_bits = 2048 by 4096Replace default_md = sha256

Save the file. Copy the content from the field “Command Line” in your browser screen (see screenshot above). paste

it in the command window NB:You may need to specify the full path to the openssl home dir (C:\OpenSSL-Win64\bin\openssl.exe ):

FSB-compliant keys and certificates management: practical guidelines

8

Execute the command. After execution you should get the following success message :

In your working dir, you get the generated files :

The file yourCN.key is your private key. Store it on a safe place for the time being. The file yourCN.csr is the certificate signing request file. Move on to next step of the procedure

2.3. SEND THE CSR TO FSB@BOSA.FGOV.BE

2.4. RETRIEVE THE CERTIFICATE AND LINK IT TO YOUR PRIVATE KEY Save the 3 certificate files in the same dircetory as where your YourCN.key file is stored. As a result,

this directory should contain the following files:

Details:o Certificate.crt = the certificate generated by the certificate authority, corresponding to

your CSR. Notice that it also contains the public key.o Chain1.crt .. chainN.crt are the chaining certificates. these certificates actually chain your

certificate with the “top root” certificate. The chain is required by the keystore management tool, to control the certificate issuer . most of the times there are 2 chain certificates yet this may vary with time.

o YourCN.csr is your certificate signing request

FSB-compliant keys and certificates management: practical guidelines

9

o YourCN.key is your private keyo YourCN.txt is the OpenSSL configuration file

Before being able to import the required files into a keystore you need to link your private key with your certificate. This generates a PKCS12 file, hereafter named certificate.pfx. Here is the detailed set of instructions to generate this file:

Open a command prompt, go to the directory where all files above are located (hereafter named MY_WORKING_DIR).

adapt and paste the following commando :MY_WORKING_DIR > PATH_TO_OPENSSL\bin\openssl pkcs12 -export -out certificate.pfx -inkey YourCN.key -in certificate.crt -name yourCN

Example: In the example hereunder, o MY_WORKING_DIR = c:\users\.reper_arnaud\Downloads , and o PATH_TO_OPENSSL = e:\openSSL-Win32

WARNING : The tool will ask you for a password, type a strengthened password and store it safely for later use in the application configuration files and/or further certificates maintenance duties

This step is completed. Your working directory now contains the following files :

2.5. CREATING A NEW KEYSTORE Start the Keystore Explorer application.

NB: at first launch, the application might request you to download some libraries from Oracle. Follow instructions on screen.

As soon as Keystore Explorer is started, you should get the following screen :

FSB-compliant keys and certificates management: practical guidelines

10

Click “Create a New KeyStore” Keystore explorer now asks you to select a format for the keystore to be created. Accept default (JKS):

Your keystore is created. Save it into your working directory. When saving the keystore, you need to specify a file name and a password. These choices are driven by your own security procedures.

2.6. STORE THE KEY PAIR AND ALL NECESSARY CERTIFICATES INTO THE JKS

The process is almost complete. You still need to (1°) import the key pair, and (2°) append chaining certificates. The following instructions drive you into these last steps.

FSB-compliant keys and certificates management: practical guidelines

11

On the welcome screen, click on the following icon: ( “Import Key Pair” ):

Keystore explorer now asks you to select a type dor the key pair to be imported. Accept default (PKCS #12) :

Browse to your your working directory, select certificate.pfx. In the field “Decryption Password”, Type the password you used when generating it:

Click “import” In the next prompt, type the Alias corresponding to your application(s) properties. (If you chose the

default Alias, make sure that your application accepts blanks in the alias name !-)

FSB-compliant keys and certificates management: practical guidelines

12

your application will use the alias to call the key pair in the signing process, so record the alias carefully.

Type a new password and save it to your password manager application or following your own safety procedure

You can also if wanted reuse the same password as the pkcs12 You should now get the following screen :

Now, Right click your certificate, and select edit certificate chain, append certificate, and Select the chain1.crt:

FSB-compliant keys and certificates management: practical guidelines

13

Repeat the same step for the other chain files. To check everything is ok, right click on the key pair once again and select the option “View Details” >

“Certificate Chain Details”:

FSB-compliant keys and certificates management: practical guidelines

14

The certificate chaining hierarchy should look like this :

save your keystore again. Now you are ready to use this keystore in your application.

2.7. PERFORM AN END TO END TESTIn order to control that applications on your server are able to properly use this security infrastructure, you can perform a test with the securedEchoService – or ask to the application team to do so, if this falls out of your scope of responsibility.The securedEchoService is a simple service exposed by the fsb to allow service consumers to control that the basic secure connectivity is OK. The test consists in issuing a request from the server, and controlling the response.All additional informations and resources required to perform the test can be found at the following URL:http://registry.fsb.pr.belgium.be/web/service-catalog/artifact/5131d6b1-2719-4ef5-9d83-f873281b3d3c?view=partner&history=3.2&submit_a317ee21bcd0700b788740890ef7af31=clickedPlease notice that the Tab « documentation » contains a document « how to use Secured Echo Service” (available in French and dutch).Once this step is completed, you are certain that the security is properly set up. You can move on to the development of your consumer.

FSB-compliant keys and certificates management: practical guidelines

15

2.8. WORKING WITH AN EXISTING KEYSTOREIf you want to work with an existing keystore, click “open an existing keystore” on the keystore explorer welcome screen and browse to the existing keystore. Enter the keystore password. Keystore explorer will show you the keystore content. From then on follow the steps described in the previous section.Keystore explorer welcome screen:

Keystore content:

FSB-compliant keys and certificates management: practical guidelines