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:
This is the template for configuring the PKI key:
% 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:
% 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.
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:
% set aaa pki trusted-certificate-authority name_of_certificate_authority allow-tunnel-authentication true/false
% 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.
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.
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.
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:
> request test-web-request url https://www.trusted-resource.com
This is an example of a successful request:
result "Request to https://www.trusted-resource.com succeeded.";
This is an example of an unsuccessful request:
"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:
% 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:
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-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.
- IKE for the gateway to identify itself to IKE. (The valid name for this identity certificate is ike.)
- EAP-IKEv2 identity certificates may have a list of SANs. One of these names must match the name of the IKEv2 connection.
- HTTPS for the gateway to identify itself to browser clients (including Compass) that you use for administering or monitoring the gateway. (The valid name for this identity certificate is https.)
- External validation (see Securing MDM-managed devices with the gateway for configuration details)
- SCEP (see Configuring certificate enrollment for the gateway for configuration details)
- EST (see Configuring certificate enrollment for the gateway for configuration details)
- Web-auth (see Configuring an external web server for authenticating gateway users for configuration details)
- SSO (see Configuring gateway Single Sign-On for CA Single Sign-On for configuration details)
Defining identity certificates
Use this template for defining an identity certificate.
% set aaa pki identity-certificate certname p12-pem-data string passphrase string
|identity-certificate certname||Name of the identity certificate (ike, https, or another name for a different certificate type).|
|p12-pem-data string||Specify the Base64-encoded PKCS#12 certificate.|
|passphrase string||Passphrase for decoding the PKCS#12 certificate.|
To determine the possible completions for an identity-certificate element:
% 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:
% 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):
% 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:
$ echo hello | base64 aGVsbG8K
Example of converting a binary pkcs12 certificate to base64 encoding:
$ 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:
% set aaa pki certificate-revocation crl <choice of following options>
|cache-size||Controls the maximum amount of gateway memory devoted to CRL caching, which can range from 0–5 MB.|
|ldap-base-url||The 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-url||This option manually specifies an alternative URL for the CRL server. Only "http" or "ldap" URLs are supported.|
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.
To configure the gateway to perform a CRL check:
% set aaa pki certificate-revocation crl policy required
To configure the gateway to override a certificate-supplied URL with an admin user-supplied URL:
% 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:
% set aaa pki certificate-revocation crl cache-size 3