Back to Contents 

Deploying a Client for HTTPS

Creation of all X.509 certificates:

• Step 1: Create the Root Certificate Authority
• Step 2: Create the client's certificate and private key
• Step 3: Create the client's certificate authority list

Client Configuration:

• Step 4:  Define the global certificate authority list
• Step 5:  Define the client security configuration
• Step 6:  Define the HTTP authentication configuration
• Step 7:  Encrypt the HTTP authentication password
• Step 8:  Configure the client to access the server

Step 1 : Create the Root Certificate Authority

• Create the root certificate authority serial file:

  $ echo 01 > MyCompanyCA.srl
   

• Create the Root Authority's Certificate Signing Request and private key:

  $ openssl req -new -out MyCompanyCA.csr -keyout MyCompanyCA.pem
   

• Create the Root Certificate Authority for a period of validity of 2 years:

  $ openssl x509 -trustout -in MyCompanyCA.csr -out MyCompanyCA.crt -req -signkey MyCompanyCA.pem -days 730
  

Note: The private key file (MyCompanyCA.pem) of a Root Certificate Authority must be handled with care. This file is responsible for the validity of all other certificates it has signed. As a result, it must not be accessible by other users.

Back to the top

Step 2 : Create the client's certificate and private key

• Create the client serial file:

  $ echo 01 > MyClient.srl

• Create the client's Certificate Signing Request and private key:

  $ openssl req -new -out MyClient.csr
  

  Note: openssl by default, outputs the private key in the privkey.pem file.

• Remove the password from the private key:

  $ openssl rsa -in privkey.pem -out MyClient.pem

  Note: The key is also renamed in MyClient.pem.

• Create the client's Certificate trusted by the Root Certificate Authority:

  $ openssl x509 -in MyClient.csr -out MyClient.crt -req -signkey MyClient.pem -CA MyCompanyCA.crt -CAkey MyCompanyCA.pem
  

Note: The purpose of the client's Certificate is to identify the client to any server; therefore the subject of the certificate must correspond to the client's identity as it is known by the servers.

Note: To import the certificate in a keystore you can create a pkcs12 certicate.

Back to the top

Step 3 : Create the client's certificate authority list

• Create the client's Certificate Authority List:

  $ openssl x509 -in MyCompanyCA.crt -text >> ClientCAList.pem

Notes: As the client trusts only the Root Certificate Authority, the list contains only that one certificate authority; all other certificates that were trusted by the Root Certificate Authority will also be considered as trusted by the client.

Back to the top

Step 4 : Define the global certificate authority list

The global certificate authority list entry defines the file containing the certificate authority list that the Genero Web Services client will use to validate all certificates coming from the different servers it will connect to. The certificate authority list entry must be defined as follows:

security.global.ca = "ClientCAList.pem"

Back to the top

Step 5 : Define the client security configuration

The client security entry defines the certificate and the associated private key that the Genero Web Services client will use during a communication with a HTTPS server. The security entry must be defined with an unique identifier (id1 in our case).

security.id1.certificate = "MyClient.crt"
security.id1.privatekey  = "MyClient.pem"

Notes: If the private key is protected with a password, you must remove it or create a script that returns the password on demand.

Back to the top

Step 6 : Define the HTTP authentication configuration

As our server supports HTTP authentication (See RFC 2617 for more details) , it is necessary to define the client login and password with the same value as registered on the server side. The following two entries must be defined with an unique identifier (id2 in our case).

authenticate.id2.login     = "mylogin"
authenticate.id2.password  = "mypassword"

Back to the top

Step 7 : Encrypt the HTTP authentication password

Due to security leaks, it is not recommended that you have a password in clear text. The Genero Web Services package provides the tool fglpass. This tool encrypts a password with a certificate that is  readable only with the associated private key. To encrypt the HTTP authentication password, do the following:

• Encrypt the clear text password with fglpass using the client certificate:

  $ fglpass -e -c MyClient.crt
Enter password :mypassword

  Note: fglpass outputs the encrypted password on the console but can be redirected to a file.

Modify the HTTP authentication password entry by specifying the security configuration to use to decrypt it (id1 in our case)

authenticate.id2.password.id1="HWTFu8QE2t3e5D4joy7js8mB95oOGTzLmcAor9j5DS+CloiliGCwZvZ9eWpfmIWSON9IwoiJheYxfnu20uaGGmmiUGiHxT6341ePXNSicu32NtlVp9t6RcS0wN/p9a6D4XtiD9iHW7iQvXhqC9uamd3gI9Q3GhHwXOMMlY//c8Y="

Note: The size of the encrypted password depends on the size of the public key, and can change according to the certificate used to encrypt it.

Back to the top

Step 8 : Configure the client to access the server

The Genero Web Services client needs a set of configuration entries to specify the security configuration and the HTTP authentication (id1 and id2, respectively) to use when accessing our server. The following entries must be defined with a unique identifier (myserver in our case):

ws.myserver.url          = "https://www.MyServer.com/cgi-bin/fglccgi.exe/ws/r/MyWebService"
ws.myserver.security     = "id1"
ws.myserver.authenticate = "id2"

Notes: The unique identifier myserver can be used in the 4GL client code instead of the real URL.

Back to the top