Skip to main content
Skip table of contents

Configuring AAA Public Key Infrastructure

The Public Key Infrastructure (PKI) subcomponent in AAA configures the certificates used for establishing the identity of clients connecting to the gateway and to the identity of the gateway itself. Within the PKI subcomponent, administrative users can also configure policies for verifying the revocation status of certificates.

There are three elements you can configure for the PKI subcomponent:

  • trusted-certificate-authority
  • identity-certificate
  • certificate-revocation

This is the template for configuring the PKI key:

BASH
% set aaa pki pki_element


Configuring trusted certificates

The trusted-certificate-authority list defines a list of certificate authorities trusted by the gateway for the purpose of authenticating:

  • Client certificates presented by Blue Cedar-secured apps
  • Servers that the gateway is securely connecting to

Because certificates are complex data structures, the CLI provides a special input mode for managing the certificates. There are two required steps and one optional step to configuring a new trusted certificate:

(Required) Perform the following command:

BASH
% set aaa pki trusted-certificate-authority name_of_certificate_authority 
certificate-pem-data string

(Required) At the prompt, enter the certificate data in the Privacy Enhanced Email (PEM) format.

BASH
Enter/paste Base64 PEM data. Enter Ctl-D to complete.

Note: The PEM file format was the original method for sending trusted certificates over email. As an ASCII format, PEM encodes binary X509 certificate data using a Base64 encoding scheme. PEM files contain only public certificate information. Most certificate management software have the ability to export to PEM.

(Optional) Specify the purpose for using a specific trusted certificate authority.

The gateway provides two options for specifying the purpose of using a trusted certificate authority:

  • Server authentication: This option specifies that the trusted certificate authority is used for authenticating other servers that the gateway wants to securely connect through HTTPS. By default, this option is set to true, which enables this option.
  • Tunnel authentication: This option specifies that the trusted certificate authority is used for authenticating clients that want to connect to the gateway via a secure tunnel (such as a Blue Cedar-secured app). By default, this option is set to true, which enables this option.

This is the template for setting the options for the purpose of using a trusted certificate authority:

BASH
% set aaa pki trusted-certificate-authority name_of_certificate_authority 
allow-tunnel-authentication true/false 

or

BASH
% set aaa pki trusted-certificate-authority name_of_certificate_authority 
allow-server-authentication true/false

By default, both the tunnel authentication and server authentication options are enabled. However, you can enable one certificate authority (CA) for one purpose and disable it for another purpose. This allows you the flexibility to manage how a trusted CA is used for authentication, which depends on your network configuration.

Example

The following example sets the purpose of the trusted certificate authority (CA) to

  • Disallow "Entrust" to be used as the CA for the gateway to authenticate itself to other servers 
  • Allow "Entrust" to be used as the CA for authenticating clients that want to securely connect to the gateway 
  • Allow "Verisign" to be used as the CA for the gateway to securely connect (via HTTPS) to other servers.

    BASH
    % set aaa pki trusted-certificate-authority entrust certificate-pem-data
    Enter/paste Base64 PEM data. Enter Ctl-D to complete.
              
    ----BEGIN CERTIFICATE---
    MIIDUzCCAjugAwIBAgIIDz3ujuueapEwDQYJKoZIhvcNAQEFBQAwNzEPMA0GA1UEAwwGQm9sdENBMRMwEQYDVQQLDApDZWRhciBIaWxsMQ8wDQYDVQQKDAZNb2NhbmEwHhcNMTMwNDIzMTUxNTE4WhcNMjMwNDIxMTUxNTE4WjA3MQ8wDQYDVQQDDAZCb2x0Q0ExEzARBgNVBAsMCkNlZGFyIEhpbGwxDzANBgNVBAoMBk1vY2FuYTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKiYrcp0i0zf5bUDfn4DGzLZNGCew0Pm94pX+QsqRdQgoNl/YddqWB2gygGhUMS67GFs+WZ0I3d8exaupFVtWJ3lU/jI3jk7lqE4g/+EgShR82D9d08nx2glqq6v46/pLcyVmRwZ4gpt7X+741/S6VSF4ldROnNIGwzkZUHDDKRKYyXjS4IFA7bDvxc9qK9yYCg0l6deUw+DA/jIHEBRq3kz0AGFs1ObK/RyfoIvIwTZp9/OZNl1E4gDR692ebUGG7VX1vke1T79ThjF2W8vjVc0tZITXrCyd3B1MMpsjVTfsaTm9wu6Q9O+oaq9X7ibqdpRzBxGfAE9ezp77UjfUFcCAwEAAaNjMGEwHQYDVR0OBBYEFOH5TcESHbGZCjDHXwpB7NhJjaGTMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAU4flNwRIdsZkKMMdfCkHs2EmNoZMwDgYDVR0PAQH/BAQDAgGGMA0GCSqGSIb3DQEBBQUAA4IBAQB5kJ/CML39GU+IJnDm1T+bYcZCLStxf/grmQZF7r+31V2/kPb+IoxvmnJ0WjF+2G9q72RSFB91d8ZJsLq02RxfUxbtRyGVsGID/NZusPN/PcUbmHUPzvbGfhdpbY7yvpu+L4g9pyHKzt00zIvXIHyXSz5XjHzVjP5yAyvN/4JvfV44OcakqttKMb06WJP5B8u7d+Hf9H1xzVu9BiTxOxxiiqeI3R9dFJxzRYc/fO8njwtOHe4bCsr9gzwxG0yESWQnTTkP5xYZhTpNCLM9Rpibv7cQUrh0qxgaXKvnRjH7z6u9V3VrkMxD3kaCuhRcSV/S2SLGg0JB5nmYhR1Lu8bu
    ---END CERTIFICATE----
    
    % set aaa pki trusted-certificate-authority entrust allow-tunnel-authentication true
    % set aaa pki trusted-certificate-authority entrust allow-server-authentication false
    % set aaa pki trusted-certificate-authority verisign allow-server-authentication true
              
    % commit

Testing the certificates from a trusted certificate authority

Follow this procedure to validate that the gateway can reach a particular resource, and in the case of HTTPS, determine if the gateway trusts the identity certificate of that resource

Get the root certificate for the server that the gateway will connect to. 

Note: Use only root certificates for a server. Leaf certificates will not work and authentication will fail. The gateway needs to build a certificate chain back to a trusted root certificate for the certificate to be considered valid.

From the CLI, enter the certificate data in the Privacy Enhanced Email (PEM) format. Use the command line from Steps 2 and 3 above to enter the PEM data.

Run this CLI command in operational mode:

BASH
> request test-web-request url https://www.trusted-resource.com
Where https://www.trusted-resource.com is the URL for the server or resource that the gateway wants to securely connect to via HTTPS.

This is an example of a successful request:

BASH
result "Request to https://www.trusted-resource.com succeeded.";

This is an example of an unsuccessful request:

BASH
"Peer certificate cannot be authenticated with given CA certificates";


Removing a certificate

If you need to update a certificate, you must remove the existing one. Use this command to remove:

BASH
% delete aaa pki trusted-certificate-authority name_of_certificate_authority


Configuring identity certificates

The identity-certificate list defines a list of certificates that can be used by the gateway to identify itself to clients connecting to it. Unlike trusted certificates, the gateway requires the public and private keys for these certificates. These certificates are stored in the PKCS#12 file format, typically in files using the .p12 extension. Because .p12 files are binary files, they must be Base64-encoded when pasted into the gateway command line. PKCS#12 files are protected with symmetric encryption, and require a passphrase to decrypt. The passphrase used to decrypt must be configured alongside the Base64-encoded .p12 file.

The PKCS#12 passphrase is stored using device specific encryption. The gateway protects the passphrase with a unique key. Consequently, any configuration file that references PKCS#12 passphrases is not portable between different Blue Cedar gateways. When sharing a configuration between devices, the passphrase must be reset after loading the saved configuration. Each passphrase appears encrypted in the configuration, as the following example shows:

BASH
passphrase TU9DREFSAAJtd36RerqaRwx2mnpr/pp22AAAAAAAAAAWq1t0JrD3OxlWXBg5nhTvdTR
jqLZu5V357XDiCA96c7Ug476dnARo6tcu/yRM0Bp1qT8UhJEsZ6xP708+5jzbhtZ9+WK4bkBqrSpcz
0iwVhzUc3VBpOb19KtHZmQl/DBthxNVRc9A4bicfT8fewV+68uP0njvJGb6Cz8q61KM/3p8HLpz+H3
au4b7LijzhkCbQfhGqxO0GqvACnX2KLdRjzpfP/SDPpN+jKXE9ZQqmAMKOSgkiqKAEiLgAWU0HcCDz
uTClLcY4sQz7rTsjyUJUM0RQzNKL5IaxOy4vccS+SZNVOn8syU3qA/m1fXNVjqdf9QT4r+VBjGXiMv
KxOHd2omhJhEXApEDlZC9raoeYBEni6vsIDxYXmKbTf26I34=;


Supported identity certificates

  • The gateway supports identity certificates that use RSA for the signing algorithm. Blue Cedar recommends lengths of 2048 bits and above.
  • The gateway supports thumbprint algorithms of these types:
    • SHA-1
    • SHA-2 set: SHA-256, SHA-384, and SHA-512

Types of identity certificates

You can specify client certificates to be used for the following types of connections. 

Defining identity certificates

Use this template for defining an identity certificate. 

BASH
% set aaa pki identity-certificate certname p12-pem-data string passphrase string


AttributeDescription
identity-certificate certnameName of the identity certificate (ike, https, or another name for a different certificate type).
p12-pem-data stringSpecify the Base64-encoded PKCS#12 certificate.
passphrase stringPassphrase for decoding the PKCS#12 certificate.

Examples

To determine the possible completions for an identity-certificate element:

BASH
% set aaa pki identity-certificate https
Possible completions:
p12-pem-data - BASE64 encoded P12 certificate/key container
passphrase - Passphrase for p12 file (stored encrypted)


To define the identity-certificate passphrase:

BASH
% set aaa pki identity-certificate https passphrase
Enter import passphrase:
Verify:


To define the identity certificate, use this command, and enter the PEM data for the identity certificate (in this example, Af8wHwYDVR0jBBgwFoAU4flNwRIdsZkKMM):

BASH
% set aaa pki identity-certificate https p12-pem-data
Enter/paste Base64 p12 PEM data. Enter Ctl-D to complete.
Af8wHwYDVR0jBBgwFoAU4flNwRIdsZkKMM


.p12 files can be exported from most certificate management software. To encode these files to Base64 format, you can use a number of freely available tools. For example, on Linux and Mac, a command-line tool called "base64" ships with most versions of the operating system. You can use this tool from a Unix prompt to convert data into base64 representation as the following example shows:

Example of base64 encoding:

BASH
$ echo hello | base64
 aGVsbG8K


Example of converting a binary pkcs12 certificate to base64 encoding:

BASH
$ base64 < identity.p12 > identity.p12.b64

Configuring certificate revocation

The certificate-revocation container allows the administrative user to configure the Certificate Revocation List (CRL). You can configure whether a CRL check is required or set the size of the cache for the CRL or (optionally) specify the URL where a CRL can be obtained.

To see the available parameters for configuring certificate revocation, use the following command:

BASH
% set aaa pki certificate-revocation crl <choice of following options>


ParameterDescription
cache-sizeControls the maximum amount of gateway memory devoted to CRL caching, which can range from 0–5 MB.
ldap-base-urlThe Base URL for LDAP server to use if a Certificate Revocation List (CRL) Distribution Point from a certificate refers to a directory name rather than an URL.
override-urlThis option manually specifies an alternative URL for the CRL server. Only "http" or "ldap" URLs are supported.
policy

Controls whether CRL checks are required or not. If a CRL check is required and a client certificate is presented to the gateway, the gateway attempts to extract the location of the CRL Distribution Point (CDP). If the CDP is a URL that contains the scheme "http" or "ldap", then the gateway downloads that CRL and its cache until its expiry date has passed. Not all certificates contain CDPs, or the certificates may contain CDPs with non-URL locations.

Values:

  • off
  • required

Examples

To configure the gateway to perform a CRL check:

BASH
% set aaa pki certificate-revocation crl policy required

To configure the gateway to override a certificate-supplied URL with an admin user-supplied URL:

BASH
% set aaa pki certificate-revocation crl override-url "ldap://loonie.acme.local:389/cn=CRL1,ou=CA,o=Acme%20Corporation,l=San%20Francisco,st=California,c=US?certificateRevocationList;"

To configure the gateway's cache-size for the CRL:

BASH
% set aaa pki certificate-revocation crl cache-size 3

On this page

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.