16.4. Management with CMP

Home Prev	cOS Stream 4.00.03 Administration Guide	Next

Overview

Certificate Management Protocol (CMP) is a method of obtaining and maintaining digital certificates using a Public Key Infrastructure (PKI). Version 2 of this protocol (CMPv2) is defined by RFC 4210 and is usually encapsulated in the HTTP protocol.

The Clavister NetShield Firewall has the capability to act as a CMP client, communicating with the CMP server of a Certificate Authority (CA) in order to fetch the certificate files required for the Certificate objects in a configuration.

Summary of Setup Steps

The setup of CMP requires the following steps:

Upload a CA root certificate to cOS Stream which can be used to authenticate the CMP server's identity.
Create a Certificate object in cOS Stream configuration for the uploaded CA root certificate file. Its Type property should be set to Remote.

Note that Certificate objects must be added as children of a CertificateStore object. The default store called ipsec could be used for this purpose but it is often better to create a new store and give it a name such as cmp. Any reference to a Certificate object must be qualified by the name of the store in which it is found. For example, mystore/my_ca_cert.
Create a CMPServer object. This will refer to the Certificate object created in the previous step.
Create one or more Certificate objects in the configuration which will hold certificates retrieved from the CMP server. Each Certificate object must be associated with the CMPServer object created in the previous step.
Use the CLI certmgr command to perform one of the following operations:
1. Initiate
  
  An existing Certificate object has no valid certificate associated with it. cOS Stream authenticates with the CMP server by using a pre-shared key (PSK), generating an RSA key pair, sending the public key to the server and getting back a signed certificate which it then associates with the Certificate object.
  
  Authenticating the client (cOS Stream) with the CMP server is done using a pair of values consisting of a username (the reference number) and a password (the PSK).
2. Update
  
  A Certificate object already has a certificate associated with it which is to be updated. cOS Stream sends a request to the CMP server to renew an existing certificate by authenticating with the current valid certificate, generating an RSA key pair, sending the public key to the server and getting back a new, signed certificate.

The above setup steps will now be described in detail in the sections that follow.

Defining a CMPServer

The CMPServer object provides the definition to locate a CMP server. The CMPServer object has the following properties:

Name

This is a human-readable string given to the object for identification purposes.
IPAddress

This defines the IP address of the server. Either the IPAddress property or the FQDN property (see below), and only one of them, is defined for a CMPServer object.
FQDN

This defines the Full Qualified Domain Name of the server. Either the IPAddress property or the FQDN property (see above), and only one of them is defined for a CMPServer object.
Port

This is the TCP port on which the CMP server will listen for HTTP/CMP traffic.
Path

This is the path to use in the HTTP request URL. See Example 16.3, “Defining a CMP Server” below for how this is specified.
CACert

This is set to be a Certificate object which already exists in the configuration. The certificate must be a CA root certificate and is used to authenticate the CMP server's identity. It is not optional at this time even if the server is trusted. A certificate must be specified.

Example 16.3. Defining a CMP Server

This example defines a CMPServer object called my_cmp_server.

It is assumed that the CMP server's CA root certificate has already been defined in the configuration as a Certificate object called cacert and this is located in the CertificateStore called cmp.

The CMP server URL is assumed to be http://ca.example.com:3076/cmp/.

Command-Line Interface

System:/> add CMPServer my_cmp_server
			CACert=cmp/cacert 
			FQDN=ca.example.com
			Port=3076
			Path=cmp/

Defining a CMP Client Certificate

A Certificate object for the client needs to be defined and associated with a CMP server before any CMP operation can be performed with it. To do this, the following Certificate properties must be set:

Type

In addition to the types Local and Remote, a Certificate object can have the type CMPv2 to indicate management with CMP. In other respects, a certificate of type CMPv2 behaves like a certificate with a type of Local.
CMPServer

This is a reference to a previously defined CMPServer object. This is the server that cOS Stream will use to manage the certificate.

Example 16.4. Adding a Client Certificate with CMP Management

In this example, a Certificate object called clcert is created and will use the CMPServer object called my_cmp_server for CMP management.

The certificate will be located in a CertificateStore called cmp which it is assumed has already been created and contains the CA root certificate:

Command-Line Interface

First, change the CLI context to the certificate store called cmp:

System:/> cc CertificateStore cmp
System:/CertificateStore/cmp>

Next, add the certificate to the store:

System:/CertificateStore/cmp> add Certificate clcert
			Type=CMPv2
			CMPServer=my_cmp_server

The CLI certmgr Command

The CLI certmgr command is used in the first step to initiate or update a certificate. A typical initiate operation would use a CLI command of the form:

System:/> certmgr -clientcert=cmp/clcert
			-initiate
			-username=user
			-password=pwd
			-subject="CN=seg.example.com"

Here, the username and password could be specified in hexadecimal by adding the -hex option. The -subject parameter must be specified

A typical update operation would use a CLI command of the form:

System:/> certmgr -update -clientcert=cmp/clcert

As shown in the examples below, after either an initiate or update operation, it is necessary to perform a second step of explicitly associating the received certificate files with the relevant certificate object.

Initiating a Certificate

When initiating a new certificate being sent from a CMP server, a Certificate object with its Type property set to CMPv2 is required which specifies the CMP server. Authentication of the client (cOS Stream) with the remote CMP server requires that the following certmgr command options must be included:

-username

This is usually the Reference Number that is required by the CMP server.
-password

This is usually the Private Shared Key (PSK) that is required by the CMP server.
-subject

Although not a direct part of authentication, the subject field of the certificate must also be specified for an initiate operation.

The way these options are used depends on the way the CMP server is configured. Usually with a public CA, both the reference number and Private Shared Key are required and these will be issued by the CA.

After the initiate operation succeeds, the certificate and private key are stored as local files and the administrator must perform the following actions manually to complete the process:

The files retrieved from the CMP server must be explicitly associated with the relevant Certificate object.
After the configuration change, an activate and commit operation must be performed so the changes become persistent.

If these manual actions are not performed, the retrieved certificate and generated private key will be lost when cOS Stream restarts.

Example 16.5. Initiating a Certificate

This example shows how the initiate operation is performed for the Certificate object called clcert using a reference number and PSK to authenticate the client (cOS Stream) with the CMP server:

It is assumed that clcert is found in the CertificateStore called cmp.

The CMP server is configured to accept a reference value of my_reference and secret value of my_secret.

Command-Line Interface

System:/> certmgr -clientcert=cmp/clcert
			-initiate
			-username=my_reference
			-password=my_secret
			-subject="CN=seg.example.com"

The administrator must now manually update the Certificate object with the following CLI commands:

System:/> cc CertificateStore cmp
System:/CertificateStore/cmp> set Certificate clcert 
			CertificateData=file://cl_newcert.der 
			PrivateKey=file://cl_newkey.pem
				
System:/CertificateStore/cmp> cc
System:/> activate

System:/> commit

Updating a Certificate

A current certificate stored by cOS Stream can be updated with a new certificate automatically retrieved from a CMP server. This time, the -username and -password options are not needed. Instead, authentication of the CMP client (cOS Stream) is done by using the still-valid certificate itself.

The newly generated private key and retrieved newly created certificate are stored as new files after download from the server. As with the initiate operation above, a manual operation is still needed to associate the received files with the relevant Certificate object. Doing this, is described as part of the example below.

Example 16.6. Updating a Certificate

This example shows how to perform an update operation for the Certificate object called clcert.

It is assumed that clcert is found in the CertificateStore called cmp.

Command-Line Interface

System:/> certmgr -update -clientcert=cmp/clcert

The administrator must now manually update the Certificate object with the following CLI commands:

System:/> cc CertificateStore cmp
System:/CertificateStore/cmp> set Certificate clcert 
			CertificateData=file://cl_newcert.der 
			PrivateKey=file://cl_newkey.pem
				
System:/CertificateStore/cmp> cc
System:/> activate

System:/> commit

Revoking a Certificate

A current certificate stored by cOS Stream can be explicitly revoked by the administrator.

Example 16.7. Revoking a Certificate

This example shows how to perform a revoke operation for the Certificate object called clcert.

It is assumed that clcert is located in the CertificateStore called cmp.

Command-Line Interface

System:/> certmgr -revoke -clientcert=cmp/clcert