Command Reference vA5(1.0) and earlier, Cisco ACE Application Control Engine
SSL Proxy Configuration Mode Commands
Downloads: This chapterpdf (PDF - 157.0KB) The complete bookPDF (PDF - 28.65MB) | Feedback

SSL Proxy Configuration Mode Commands

Table Of Contents

SSL Proxy Configuration Mode Commands

(config-ssl-proxy) authgroup

(config-ssl-proxy) cert

(config-ssl-proxy) chaingroup

(config-ssl-proxy) crl

(config-ssl-proxy) key

(config-ssl-proxy) ocspserver

(config-ssl-proxy) revcheckprio

(config-ssl-proxy) ssl advanced-options


SSL Proxy Configuration Mode Commands

SSL proxy configuration mode commands allow you to define the Secure Sockets Layer (SSL) parameters that the ACE SSL proxy service uses in either SSL termination (proxy server service) or SSL initiation (proxy client service) during the SSL handshake.

To create a new proxy service (or edit an existing proxy service) and access SSL proxy configuration mode, use the ssl-proxy service command in configuration mode. The CLI prompt changes to (config-ssl-proxy). Use the no form of this command to delete an existing SSL proxy service.

ssl-proxy service pservice_name

no ssl-proxy service pservice_name

Syntax Description

pservice_name

Name of the SSL proxy service. Enter an unquoted text string with no spaces and a maximum of 64 alphanumeric characters.


Command Modes

Configuration mode

Admin and user contexts

Command History

ACE Module Release
Modification

3.0(0)A1(2)

This command was introduced.


ACE Appliance Release
Modification

A1(7)

This command was introduced.


Usage Guidelines

The commands in this mode require the SSL feature in your user role. For details about role-based access control (RBAC) and user roles, see the Virtualization Guide, Cisco ACE Application Control Engine.

When you create a SSL proxy service, the CLI changes to the SSL proxy configuration mode, where you define the following SSL proxy service attributes:

Client authentication group—See the (config-ssl-proxy) authgroup command.

Certificate—See the (config-ssl-proxy) cert command.

Client authentication using CRLs—See the (config-ssl-proxy) crl command

Chain group—See the (config-ssl-proxy) chaingroup command.

Key pair—See the (config-ssl-proxy) key command.

Parameter map—See the (config-ssl-proxy) ssl advanced-options command.

Examples

To create the SSL proxy service PSERVICE_SERVER, enter:

host1/Admin(config)# ssl-proxy service PSERVICE_SERVER
host1/Admin(config-ssl-proxy)#
 
   

To delete an existing SSL proxy service, enter:

host1/Admin(config)# no ssl-proxy PSERVICE_SERVER

Related Commands

(config-ssl-proxy) authgroup

(config-ssl-proxy) cert

(config-ssl-proxy) chaingroup

(config-ssl-proxy) key

(config-ssl-proxy) ssl advanced-options

(config-ssl-proxy) authgroup

To specify the certificate authentication group that the ACE uses during the Secure Sockets Layer (SSL) handshake and enable client authentication on this SSL-proxy service, use the authgroup command. Use the no form of this command to delete a certificate authentication group from the SSL proxy service.

authgroup group_name

no authgroup group_name

Syntax Description

group_name

Name of an existing certificate authentication group.


Command Modes

SSL proxy configuration mode

Admin and user contexts

Command History

ACE Module Release
Modification

A2(1.0)

This command was introduced.


ACE Appliance Release
Modification

A3(1.0)

This command was introduced.


Usage Guidelines

When you enable client authentication, a significant performance decrease may occur in the ACE ACE.

Examples

To specify the certificate authentication group AUTH-CERT1, enter:

host1/Admin(config-ssl-proxy)# authgroup AUTH-CERT1
 
   

To delete the certificate authentication group AUTH-CERT1 from the SSL proxy service, enter:

host1/Admin(config-ssl-proxy)# no authgroup AUTH-CERT1

Related Commands

(config) crypto chaingroup

(config-parammap-ssl) authentication-failure

(config-ssl-proxy) cert

(config-ssl-proxy) key

(config-ssl-proxy) ssl advanced-options

 
   

(config-ssl-proxy) cert

To specify the certificate that the ACE uses during the Secure Sockets Layer (SSL) handshake to prove its identity, use the cert command. Use the no form of this command to delete a certificate file from the SSL proxy service.

cert cert_filename | cisco-sample-key

no cert cert_filename | cisco-sample-key

Syntax Description

name

Name of an existing certificate file loaded on the ACE. Enter an unquoted text string with no spaces and a maximum of 40 alphanumeric characters. To display a list of available certificate files, use the do show crypto files command.

cisco-sample-cert

Specifies the self-signed certificate named cisco-sample-cert that is preinstalled on the ACE. This file is available for use in any context with the filename remaining the same in each context.


Command Modes

SSL proxy configuration mode

Admin and user contexts

Command History

ACE Module Release
Modification

3.0(0)A1(2)

This command was introduced.

A2(3.0)

Added the sample-cisco-cert keyword.


ACE Appliance Release
Modification

A1(7)

This command was introduced.

A4(1.0)

Added the sample-cisco-cert keyword.


Usage Guidelines

The public key embedded in the certificate that you select must match the public key in the key pair file that you select. To verify that the public keys in the two files match, use the crypto verify command in the Exec mode.

Examples

To specify the certificate in the certificate file MYCERT.PEM, enter:

host1/Admin(config-ssl-proxy)# cert MYCERT.PEM
 
   

To delete the certificate in the certificate file MYCERT.PEM from the SSL proxy service, enter:

host1/Admin(config-ssl-proxy)# no cert MYCERT.PEM

Related Commands

crypto verify

(config) crypto chaingroup

(config-ssl-proxy) authgroup

(config-ssl-proxy) chaingroup

(config-ssl-proxy) key

(config-ssl-proxy) ssl advanced-options

(config-ssl-proxy) chaingroup

To specify the certificate chain group that the ACE sends to its peer during the Secure Sockets Layer (SSL) handshake, use the chaingroup command. Use the no form of this command to delete a certificate chain group from the SSL proxy service.

chaingroup group_name

no chaingroup group_name

Syntax Description

group_name

Name of an existing certificate chain group.


Command Modes

SSL proxy configuration mode

Admin and user contexts

Command History

ACE Module Release
Modification

3.0(0)A1(2)

This command was introduced.


ACE Appliance Release
Modification

A1(7)

This command was introduced.


Usage Guidelines

The ACE includes the certificate chain with the certificate that you specified for the SSL proxy service.

When a change occurs in a chain-group certificate, the change takes effect when you read the associated chain group through the chaingroup command.

Examples

To configure the ACE SSL proxy service to send the certificate chain group MYCHAINGROUP to its peer during the SSL handshake, enter:

host1/Admin(config-ssl-proxy)# chaingroup MYCHAINGROUP
 
   

To delete the certificate chain group MYCHAINGROUP from the SSL proxy service, enter:

host1/Admin(config-ssl-proxy)# no chaingroup MYCHAINGROUP

Related Commands

(config) crypto chaingroup

(config-ssl-proxy) authgroup

(config-ssl-proxy) cert

(config-ssl-proxy) key

(config-ssl-proxy) ssl advanced-options

(config-ssl-proxy) crl

To determine which certificate revocation lists (CRLs) to use for client or server authentication, use the crl command. Use the no form of this command to disable the use of CRL certificates during authentication.

crl crl_name | best- effort

no crl crl_name | best-effort

Syntax Description

crl_name

Name that you assigned to the CRL when you downloaded it using the configuration mode crypto crl command. See (config) crypto crl for more information.

best-effort

Specifies that the ACE scans each certificate to determine if it contains a CDP pointing to a CRL in the certificate extension and then retrieves the CRLs from that location, if the CDP is valid.


Command Modes

SSL proxy configuration mode

Admin and user contexts

Command History

ACE Module Release
Modification

A2(1.0)

This command was introduced.

A2(2.0)

This command was revised for server authentication.


ACE Appliance Release
Modification

A3(1.0)

This command was introduced.

A4(1.0)

This command was revised for server authentication and the CRLs per context were increased from four to eight.


Usage Guidelines

By default, the ACE does not use CRLs during client or server authentication. You can configure the SSL proxy service to use a CRL by either of the following methods:

The ACE can scan each certificate for the service to determine if it contains a CRL Distribution Point (CDP) pointing to a CRL in the certificate extension and then retrieve the CRL from that location if the CDP is valid. If the CDP has an http:// or ldap:// based URL, it uses the URL to download the CRL to the ACE module.

You can manually configure the download location for the CRL from which the ACE retrieves it.

You can configure a maximum of eight CRLs per context.

By default, the ACE does not reject certificates when the CRL in use has passed its update date. To configure the ACE to reject certificates when the CRL is expired, use the expired-crl reject command in parameter map SSL configuration mode.

When attempting to download a CRL when best-effort CRLs are configured:

The ACE considers only the first four CDPs. From the CDPs obtained from certificate, the ACE only considers valid and complete CDPs for the downloading of the CRLs. If a CDP leads to the successful downloading of the CRL, ACE does not consider the subsequent CDPs for CRL downloads.

If none of the first four CDPs present in the certificate are valid to proceed with the downloading of the CRL, the ACE considers the certificate as revoked unless you configured the authentication-failure ignore command in parameter map SSL configuration mode.

If the ACE fails to download a CRL after trying four valid CDPs, the ACE aborts its initiated SSL connection unless you configured the authentication-failure ignore command in parameter map SSL configuration mode.

If the ACE detects CDP errors in the presented certificates or errors that occur during a CRL download, the ACE rejects the SSL connection unless you configured the cdp-errors ignore command in parameter map SSL configuration mode

The ACE skips malformed CDPs and processes subsequent CDPs. To display CDP error statistics including the number of malformed CDPs, use the show crypto cdp-errors command.

Examples

To enable the CRL1 CRL for authentication on an SSL proxy service, enter:

host1/Admin(config-ssl-proxy)# crl CRL1
 
   

To scan the client certificate for CRL information, enter:

host1/Admin(config-ssl-proxy)# crl best-effort
 
   

To disable the use of a downloaded CRL during authentication, enter:

host1/Admin(config-ssl-proxy)# no crl CRL1
 
   

To disable the use of CRL client certificates during authentication, enter:

host1/Admin(config-ssl-proxy)# no crl best-effort

Related Commands

crypto crlparams

(config) crypto crl

(config-parammap-ssl) authentication-failure

(config-parammap-ssl) cdp-errors ignore

(config-parammap-ssl) expired-crl reject

(config-ssl-proxy) authgroup

(config-ssl-proxy) cert

(config-ssl-proxy) chaingroup

(config-ssl-proxy) key

(config-ssl-proxy) ssl advanced-options

(config-ssl-proxy) key

To specify the key pair that the ACE uses during the Secure Sockets Layer (SSL) handshake for data encryption, use the key command. Use the no form of this command to delete a private key from the SSL proxy service.

key key_filename | cisco-sample-key

no key key_filename | cisco-sample-key

Syntax Description

key_filename

Name of an existing key pair file loaded on the ACE. Enter an unquoted text string with no spaces and a maximum of 40 alphanumeric characters.

cisco-sample-key

Specifies the sample RSA 1024-bit key pair named cisco-sample-key that is preinstalled on the ACE. This file is available for use in any context with the filename remaining the same in each context.


Command Modes

SSL proxy configuration mode

Admin and user contexts

Command History

ACE Module Release
Modification

3.0(0)A1(2)

This command was introduced.

A2(3.0)

Added the sample-cisco-key keyword.


ACE Appliance Release
Modification

A1(7)

This command was introduced.

A4(1.0)

Added the sample-cisco-key keyword.


Usage Guidelines

The public key in the key pair file that you select must match the public key embedded in the certificate that you select. To verify that the public keys in the two files match, use the crypto verify command in the Exec mode.

Examples

To specify the private key in the key pair file MYKEY.PEM for the SSL proxy service, enter:

host1/Admin(config-ssl-proxy)# key MYKEY.PEM
 
   

To delete the private key in the key pair file MYKEY.PEM from the SSL proxy service, enter:

host1/Admin(config-ssl-proxy)# no key MYKEY.PEM

Related Commands

crypto verify

(config-ssl-proxy) authgroup

(config-ssl-proxy) cert

(config-ssl-proxy) chaingroup

(config-ssl-proxy) ssl advanced-options

(config-ssl-proxy) ocspserver

To apply an OCSP server to an SSL proxy service, use the ocspserver command. Use the no form of this command to remove the association of an OCSP server with the SSL proxy service.

ocspserver ocsp_server_name | best-effort

no ocspserver ocsp_server_name | best-effort

Syntax Description

ocsp_server_name

Identifier of an OCSP server that you want to apply to this SSL proxy service. Enter the name of an existing OCSP server as a text string with no spaces and a maximum of 64 alphanumeric characters.

best-effort

Specifies that the ACE attempts to obtain certificate revocation information from an OCSP server on a best-effort basis. When you configure this keyword, the ACE extracts the OCSP server information (up to four OCSP server information elements) from the client certificate. This keyword forces the ACE to look for the AuthorityInfoAccess (AIA) extension in the incoming client or server certificates.


Command Modes

SSL proxy configuration mode

Admin and user contexts

Command History

ACE Module Release
Modification

A5(1.0)

This command was introduced.


ACE Appliance Release
Modification

A5(1.0)

This command was introduced.


Usage Guidelines

You can apply a maximum of 10 OCSP servers to an SSL proxy service.

The format of the AIA extension is as follows:

authorityInfoAccess = OCSP;URI: http://test1.ocsp.ve/,OCSP;URI:http://test2.ocsp.ve/
 
   

If this extension is missing from a certificate when best-effort is configured, the certificate is considered to be revoked.

Examples

to apply the OCSP_SERVER1 OCSP server to the PSERVICE_SERVER SSL proxy service, enter the following commands:

host1/Admin(config)# ssl-proxy service PSERVICE_SERVER
host1/Admin(config-ssl-proxy)# ocspserver OCSP_SERVER1

To apply a best-effort OCSP server to an SSL proxy service, enter the following commands:

host1/Admin(config)# ssl-proxy service PSERVICE_SERVER
host1/Admin(config-ssl-proxy)# ocspserver best-effort

To remove an OCSP server from an SSL proxy service, enter the following command;

host1/Admin(config-ssl-proxy)# no ocspserver OCSP_SERVER1
 
   

Related Commands

show crypto

(config) crypto ocspserver

(config-ssl-proxy) revcheckprio

When you configure both OCSP and CRLs in the same SSL proxy service, you can control the order in which the ACE uses these two resources to check the revocation status of SSL certificates. To configure the order of revocation checking, use the revcheckprio command. Use the no form of this command to reset the ACE behavior to the default of checking the OCSP server first and then the CRLs for certificate revocation.

revcheckprio crl-ocsp | ocsp-crl

no revcheckprio crl-ocsp | ocsp-crl

Syntax Description

crl-ocsp

Instructs the ACE to use a CRLs first and then OCSP to determine the revocation status of a client SSL certificate.

ocsp-crl

(Default) Instructs the ACE to use OSCP first and then CRLs to determine the revocation status of a client SSL certificate.


Command Modes

SSL proxy configuration mode

Admin and user contexts

Command History

ACE Module Release
Modification

A5(1.0)

This command was introduced.


ACE Appliance Release
Modification

A5(1.0)

This command was introduced.


Usage Guidelines

If either OCSP or CRLs, but not both methods, are applied to an SSL proxy service, this command is not configurable.

The coexistence of CRLs and OCSP server information and traversal through them may lead to extended handshake completion time and the overall performance of the ACE may degrade.

You can apply a maximum of 10 OCSP servers to an SSL proxy service.

The format of the AIA extension is as follows:

authorityInfoAccess = OCSP;URI: http://test1.ocsp.ve/,OCSP;URI:http://test2.ocsp.ve/
 
   

If this extension is missing from a certificate when best-effort is configured, the certificate is considered to be revoked.

The default revocation check priority order (revcheckprio ocsp-crl) is not displayed in the output of the show running-config command even if that priority order is configured.

Examples

To configure the ACE to check revocation status with CRLs first and then OCSP, enter the following commands:

host1/Admin(config)# ssl-proxy service PSERVICE_SERVER
host1/Admin(config-ssl-proxy)# revcheckprio crl-ocsp
 
   

To reset the ACE behavior to the default of checking the OCSP server first and then the CRLs for certificate revocation, enter the following command:

host1/Admin(config-ssl-proxy)# no revcheckprio crl-ocsp
 
   
 
   

Related Commands

show crypto

(config) crypto ocspserver

(config-ssl-proxy) ssl advanced-options

To associate a context Secure Sockets Layer (SSL) parameter map with the SSL proxy server service, use the ssl advanced-options command. Use the no form of this command to remove the association of an SSL parameter map with the SSL proxy service.

ssl advanced-options parammap_name

no ssl advanced-options parammap_name

Syntax Description

parammap_name

Name of an existing SSL parameter map.


Command Modes

SSL proxy configuration mode

Admin and user contexts

Command History

ACE Module Release
Modification

3.0(0)A1(2)

This command was introduced.


ACE Appliance Release
Modification

A1(7)

This command was introduced.


Usage Guidelines

This command has no usage guidelines.

Examples

To associate the parameter map PARAMMAP_SSL with the SSL proxy service, enter:

host1/Admin(config-ssl-proxy)# ssl advanced-options PARAMMAP_SSL
 
   

To remove the association of an SSL parameter map PARAMMAP_SSL with the SSL proxy service, enter:

host1/Admin(config-ssl-proxy)# no ssl advanced-options PARAMMAP_SSL

Related Commands

(config) parameter-map type

(config-ssl-proxy) authgroup

(config-ssl-proxy) cert

(config-ssl-proxy) chaingroup

(config-ssl-proxy) key