-
CSS Advanced Configuration Guide (Software Version 7.10)
-
Index
-
About This Guide
-
Configuring the CSS Domain Name Service
-
Configuring DNS Sticky
-
Configuring a CSS as a Content Routing Agent
-
Configuring a Client Side Accelerator
-
Configuring Network Proximity
-
Configuring VIP and Virtual IP Interface Redundancy
-
Configuring Redundant Content Services Switches
-
Configuring Content Replication
-
Configuring SSL Termination on the CSS
-
Configuring Firewall Load Balancing
-
Using the CSS Scripting Language
-
Table Of Contents
Configuring SSL Termination on the CSS
SSL Public Key Infrastructure Overview
SSL Module Cryptography Capabilities
SSL Module Termination Overview
SSL Configuration Quick Starts
RSA Certificate and Key Generation Quick Start
RSA Certificate and Key Import Quick Start
SSL Service and Content Rule Quick Start
Configuring SSL Certificates and Keys
Importing or Exporting Certificates and Private Keys
Configuring the Default SFTP or FTP Server to Import Certificates and Private Keys
Transferring Certificates and Private Keys to the CSS
Generating Certificates and Private Keys in the CSS
Generating Diffie-Hellman Key Parameters
Generating a Certificate Signing Request Using an RSA Key
Generating a Self-Signed Certificate
Associating Certificates and Private Keys in the CSS
Associating a Certificate to a File
Associating an RSA Key Pair to a File
Associating a DSA Key Pair to a File
Associating Diffie-Hellman Parameters to a File
Verifying a Certificate Against a Key Pair
Showing Certificate and Key Pair Information
Showing SSL Diffie-Hellman Parameters
Showing SSL Certificates, Key Pairs, and Diffie-Hellman Parameter Files
Removing Certificates and Private Keys from the CSS
Adding a Description to an SSL Proxy List
Configuring Virtual SSL Servers for an SSL Proxy List
Creating an SSL Proxy Configuration ssl-server Index
Specifying a Virtual IP Address
Specifying the RSA Certificate Name
Specifying the RSA Key Pair Name
Specifying the DSA Certificate Name
Specifying the DSA Key Pair Name
Specifying the Diffie-Hellman Parameter File Name
Specifying SSL Session Cache Timeout
Specifying SSL Session Handshake Renegotiation
Specifying SSL TCP Client-Side Connection Timeout Values
Specifying SSL TCP Server-Side Connection Timeout Values
Adding SSL Proxy Lists to Services
Creating an SSL Service for an SSL Module
Specifying the SSL Acceleration Service Type
Disabling Keepalive Messages for the SSL Module
Adding SSL Proxy Lists to a Service
Specifying the SSL Session ID Cache Size
Configuring an SSL Content Rule
Showing SSL Proxy Configuration Information
Example SSL Proxy Configurations
Processing of SSL Flows by the SSL Module
SSL Transparent Proxy Configuration - One SSL Module
SSL Transparent Proxy Configuration - Two SSL Modules
SSL Full Proxy Configuration - One SSL Module
Configuring SSL Termination on the CSS
This chapter describes how to configure the CSS and the SSL Acceleration Module to perform Secure Sockets Layer (SSL) termination between a client and servers. It also provides an overview on SSL as implemented by the SSL Acceleration Module in the CSS. Information in this chapter applies only to the Cisco CSS 11503 and CSS 11506 containing an SSL Acceleration Module (hereinafter referred to as the SSL module).
Note
The SSL feature is intended for use with the optional SSL module.
This chapter contains the following sections:
•
•
•
•
•
•
•
SSL Cryptography Overview
Secure Sockets Layer (SSL) is an applications-level protocol that provides encryption technology for the Internet ensuring secure transactions, such as the transmission of credit card numbers for e-commerce websites. SSL provides the secure transaction of data between a client and a server through a combination of privacy, authentication, and data integrity. SSL relies upon certificates, private-public key exchange pairs, and Diffie-Hellman key agreement parameters for this level of security.
The CSS uses the SSL module and a special set of SSL commands to perform the SSL cryptographic functions between the client and the HTTP servers. The SSL functions include user authentication, private-key and public-key generation, certificate management, and data packet encryption and decryption.
A typical SSL session with the SSL module requires encryption ciphers to establish and maintain the secure connection. Cipher suites provide the cryptographic algorithms required by the SSL module to perform key exchange, authentication, and Message Authentication Code (MAC). See "Specifying Cipher Suites" in this chapter for details about the supported cipher suites.
This section provides an overview on SSL cryptography as implemented through the SSL module in the CSS. It covers:
•
•
Note
Although there are very few clients on the market today that support only SSL version 2.0, if the client supports only version 2.0 the SSL module will be unable to pass network traffic.
SSL Public Key Infrastructure Overview
SSL provides authentication, encryption, and data integrity in a Public Key Infrastructure (PKI). PKI is a set of policies and procedures to establish a secure information exchange between devices. Three fundamental elements characterize the PKIs used in asymmetric cryptography. These three elements provide a secure system for deploying e-commerce and a reliable environment for building virtually any type of electronic transactions, from corporate intranets to Internet-based e-business applications.
These elements include:
Confidentiality
Confidentiality means that unintended users cannot view the data. In PKIs, confidentiality is achieved by encrypting the data through a variety of methods. In SSL, specifically, large amounts of data are encrypted using one or more symmetric keys that are known only by the two endpoints. Because the symmetric key is usually generated by one of the endpoints, it must be transmitted securely to the other endpoint. Secure transmittal of a symmetric key is generally achieved by two mechanisms, key exchange or key agreement.
Key exchange is the most common of these two secure transmittal mechanisms. In key exchange, one device generates the symmetric key and then encrypts it using an asymmetric encryption scheme before transmitting it to the other side. Asymmetric encryption requires both devices have a public key and a private key. The two keys are mathematically related; data that can be encrypted by the public key can be decrypted by the private key, and vice versa. The most commonly used key exchange algorithm is the Rivest Shamir Adelman (RSA) algorithm.
For SSL, the sender encrypts the symmetric keys with the public key of the receiver. This ensures that the private key of the receiver is the only key that can decrypt the transmission. The security of asymmetric encryption depends entirely on the fact that the private key is only known by the owner and not by any other party. If this key were compromised for any reason, a fraudulent Web user (or website) could decrypt the stream containing the symmetric key and could decrypt the entire data transfer.
In key agreement, the two sides involved in a data exchange cooperate to generate a symmetric (shared) key. The most common key agreement algorithm is the Diffie-Hellman algorithm Diffie-Hellman depends on certain parameters to generate the shared key that is calculated and exchanged between the client and the server.
Authentication
Authentication is necessary for one or more devices in the exchange to verify that the party to whom they are talking to is really who they claim to be. For example, assume a client is connecting to an e-commerce website. Before sending sensitive information such as a credit card number, the client verifies that the server is an e-commerce website. In certain instances, it may be necessary for both the client and the server to authenticate themselves to each other before beginning the transaction. In a financial transaction between two banks, both the client and the server need to be confident that the other is who they say they are. SSL facilitates this authentication through the use of digital certificates.
Digital certificates are a form of digital identification to prove the identity of the client to the server. A Certificate Authority (CA) issues digital certificates in the context of a PKI, which uses public-key and private-key encryption to ensure security. CAs are trusted authorities who "sign" certificates to verify their authenticity. The client or servers connected to the CSS must have trusted certificates from the same CA, or from different CAs in a hierarchy of trusted relationships (for example, "A" trusts "B," and "B" trusts "C," therefore "A" trusts "C").
A certificate ensures that the identification information is correct, and that the public key actually belongs to that client or server. Digital certificates contain information such as details about the owner, details about the certificate issuer, the owner's public key, validity and expiration dates, and associated privileges.
Upon receiving a certificate, a client can connect to the certificate issuer and verify the validity of the certificate using the issuer's public key. This ensures that the certificate is actually issued and signed by an authorized entity. A certificate remains valid until it expires or is terminated.
Message Integrity
Message integrity is a means of assuring the recipient of a message that the contents of the message have not been tampered with during transit. SSL achieves this by applying a message digest to the data before transmitting it. A message digest is a function that takes an arbitrary length message and outputs a fixed-length string that is characteristic of the message.
An important property of the message digest is that it is extremely difficult to reverse. Simply appending a digest of the message to itself before sending it is not enough to guarantee integrity. An attacker can change the message and then change the digest accordingly. Encoding the message digest with the sender's private key creates a Message Authentication Code (MAC), the message integrity algorithm, which the recipient can then decode using the sender's public key. SSL supports two different algorithms for a MAC: Message Digest 5 (MD5) and Secure Hash Algorithm (SHA).
This integrity scheme, however, does not work if the sender's private key is compromised. The attacker can now forge the sender's MACs. Message integrity also depends heavily on the protection of private keys. This process is known as digital signing.
RSA key pairs are effective for signing the MAC. However, it may be advantageous to separate the functions of key exchange and signing. The Digital Signature Algorithm (DSA) is an SSL algorithm that is used strictly for digital signatures but not for key exchange.
DSA was standardized as FIPS-186, which is the Digital Signature Standard (DSS). DSA and DSS can be used interchangeably. DSS uses the same crypto-math as Diffie-Hellman and requires parameters similar to Diffie-Hellman to generate keys. Additionally, DSS is restricted for use only with the Secure Hash Algorithm 1 (SHA-1) message digest.
SSL Module Cryptography Capabilities
Table 9-1 provides information on the SSL cryptography capabilities of the SSL module.
Table 9-1 SSL Module SSL Cryptography Capabilities
SSL versions
SSL version 3.0 and Transport Layer Security (TLS) version 1.0
Public key exchange and key agreement algorithms
•
•
•
Encryption types
•
•
•
Refer to Table 9-12 for a list of supported cipher suites and key encryption types.
Hash types
•
•
Refer to Table 9-12 for a list of supported cipher suites and hash types.
Digital certificates
The SSL module supports all major digital certificates from Certificate Authorities (CAs), including those listed below:
•
•
•
•
•
•
•
1 The SSL module supports the importing of 2048-bit DSA key pairs. The SSL module does not support the generation of 2048-bit DSA key pairs.
SSL Module Termination Overview
The SSL module installs in the CSS chassis and operates as a virtual SSL server by adding security services between the Web browsers (the client) and HTTP servers. The 11500 series CSS supports multiple SSL modules, up to two in a CSS 11503 and up to four in a CSS 11506. Each SSL module terminates SSL connections received from a client.
To terminate SSL flows, the SSL module functions as a proxy server, which means that it is the TCP endpoint for inbound SSL traffic. The SSL module maintains a separate TCP connection for each side of the communications, the client side and the server side. The proxy server can perform both TCP and SSL handshakes.
Once the connection is terminated, the SSL module decrypts the data and transmits the data as clear text to the server. On the outbound flow from the CSS, the SSL module encrypts the data received from the server and sends the data back to the client.
SSL termination from the client and initiation of HTTP connections to servers requires the use of an SSL proxy list to configure the flow of information to and from an SSL module. You add an SSL proxy list to an SSL service to define how an SSL module processes SSL requests for content.
The SSL module is responsible for all user authentication, public/private key generation, certificate management, and packet encryption and decryption functions between the client and the server. It is dependent on the Switch Module to provide the interface for processing network traffic and the Switch Control Module (SCM) to send and receive configuration information.
The CSS stores all certificates and keys on the SCM disk. The CSS supports up to 256 certificates and 256 key-pairs, which equals approximately 3 MB of storage space on the disk. The CSS stores all certificate- and key-related files in a secure location on the disk. When processing connections, the CSS loads the certificates and keys into volatile memory on the SSL module for faster access.
No network traffic is sent to an SSL module from the SCM until an SSL content rule is activated to:
•
•
•
SSL Configuration Quick Starts
This section provides a quick overview on how to manage SSL certificates in the CSS, create an SSL proxy list, and add the SSL proxy list to an SSL service. Each step includes the CLI command required to complete the task. RSA has been chosen for the quick start procedures in this section because it is a popular public-key algorithm for encryption and authentication.
This section includes the following quick start procedures:
•
•
•
RSA Certificate and Key Generation Quick Start
Table 9-2 provides an overview of the steps required to generate and associate an RSA key pair and certificate in the CSS. Key and certificate generation may be necessary in instances when you do not have pre-existing keys or certificates for the CSS. You may want to initially generate RSA keys and temporary certificates on the CSS for internal SSL testing until the Certificate Authority responds to the certificate request and returns the authentic certificate. A generated certificate is temporary and expires in 30 days.
RSA Certificate and Key Import Quick Start
Table 9-3 provides an overview of the steps required to import and associate an RSA certificate and key pair to the CSS from a remote server.
SSL Proxy List Quick Start
Table 9-4 provides an overview of the steps required to create an SSL proxy list (for an RSA certificate and key pair).
SSL Service and Content Rule Quick Start
Table 9-5 provides an overview of the steps required to create an SSL service, including adding the SSL proxy list to the service and creating an SSL content rule.
Configuring SSL Certificates and Keys
Before creating an SSL proxy list and adding the SSL proxy list to an SSL service, you must load a set of digital certificates and public/private key pairs on the CSS disk (flash disk or hard disk). The digital certificates and key pairs are a form of digital identification for user authentication. Certificates are issued by Certificate Authorities (CAs) such as VeriSign® and Thawte®. Each certificate includes the name of the issuing authority, the name of the entity that the certificate was issued, the entity's public key, and timestamps that indicate the certificate's expiration date. You can use files received from a CA, import the certificate and keys from an existing secure server, or generate your own certificate and keys on the CSS.
The CSS supports the generation of certificates and keys directly within the CSS for purposes of testing. Your requirement to use generated certificates and keys instead of certificates and keys from a trusted authority depends on your environment. For example, the use of the CSS and SSL for a company's internal Web site may not require the use of certificates from a trusted CA. A certificate and key pair generated within the CSS may be sufficient to satisfy the intranet SSL requirement.
The CSS stores digital certificates and key pairs in encrypted files in a secure area on the CSS.
Caution
This section covers:
•
•
•
•
•
Note
Importing or Exporting Certificates and Private Keys
You can import preexisting or new certificates and private keys to the CSS disk from a file, or a series of files, that are stored on a remote secure server. To transfer these files, Cisco Systems recommends that you use a secure encrypted transport mechanism between the CSS and the remote server. The CSS supports the Secure Shell protocol (SSHv2), which provides secure encryption communications between two hosts over an insecure network. The CSS supports file transport between network devices using the Secure File Transfer Protocol (SFTP) and the File Transfer Protocol (FTP). Of the two file transport protocols, Cisco Systems recommends SFTP as the transport mechanism of choice. It is similar to FTP except that it uses a secure and encrypted connection.
Before you import certificates or keys to the CSS:
•
Note
•
Caution
Configuring the Default SFTP or FTP Server to Import Certificates and Private Keys
Before you begin, use the ftp-record command to define the SFTP or FTP server that you intend to use to download imported certificates and private keys to the CSS disk. For details about using the ftp-record command to create an SFTP or FTP record file to use when accessing the server from the CSS, refer to the Cisco Content Services Switch Administration Guide, Chapter 1, Logging in and Getting Started.
Note
For example, to define the ssl_record, enter:
# ftp-record ssl_record 192.168.19.21 johndoe "abc123" /home/johndoeTransferring Certificates and Private Keys to the CSS
Use the copy ssl command to facilitate the import or export of certificates and private keys from or to the CSS. The CSS stores all imported files in a secure location on the CSS. This command is available only in SuperUser mode.
The syntax for this command is:
copy ssl [protocol] ftp_record [import filename [format] "password" {"passphrase"}|export filename2 "password"]
The variables are:
•
•
•
•
•
–
–
–
•
•
Note
•
•
Note
For example, to import the rsacert.pem certificate from a remote server to the CSS, enter:
# copy ssl sftp ssl_record import rsacert.pem PEM "passwd123"ConnectingCompleted successfullyFor example, to import the rsakey.pem certificate from a remote server to the CSS, enter:
# copy ssl sftp ssl_record import rsakey.pem PEM "passwd123"ConnectingCompleted successfullyTo export the rsacert.pem certificate from the CSS to a remote server, enter:
# copy ssl sftp ssl_record export rsacert.pem "passwd123"If the copy ssl command fails to import certificates or keys verify the following areas:
•
•
•
•
Generating Certificates and Private Keys in the CSS
If you do not have preexisting keys, Diffie-Hellman parameters, and certificates for the CSS, you may want to generate them on the CSS disk for purposes of testing. The CSS includes a series of certificate and private key management utilities. These utilities simplify the process of generating an RSA private key, DSA private key, a Diffie-Hellman parameter file, a certificate signing request (CSR), and a self-signed temporary certificate.
Note
A generated certificate is temporary and expires in 30 days.This section covers:
•
•
•
Generating an RSA Key Pair
Use the ssl genrsa command to generate an RSA private/public key pair for asymmetric encryption. RSA key pairs are used to sign and encrypt packet data, and they are a requirement before another device (client or server) can exchange an SSL certificate with the CSS. The key pair refers to a public key and its corresponding private (secret) key. The CSS stores the generated RSA key pair as a file on the CSS.
The syntax for this command is:
ssl genrsa filename numbits "password"
The variables are:
•
•
•
For example, to generate the RSA key pair myrsakeyfile1, enter:
(config) # ssl genrsa myrsakeyfile1 1024 "passwd123"Please be patient this could take a few minutesAfter you generate an RSA key pair, you can generate a Certificate Signing Request (CSR) file for the RSA key pair file and transfer the certificate request to the Certificate Authority (CA). This provide an added layer of security because the RSA private key originates directly within the CSS and does not have to be transported externally. You can then create a temporary certificate for internal testing until the CA responds to the certificate request and returns the authentic certificate. Each generated key pair must be accompanied by a certificate to work.
You must also associate an RSA key pair name to the generated RSA key pair, as discussed in the "Associating Certificates and Private Keys in the CSS" section of this chapter.
Generating a DSA Key Pair
Use the ssl gendsa command to generate a DSA private/public key pair for asymmetric encryption. DSA is the public key exchange cryptographic system developed by the National Institutes of Science and Technology. DSA can only be used for digital signatures (signings) but not for key private/public exchange. The CSS stores the generated DSA key pair as a file on the CSS.
The syntax for this command is:
ssl gendsa filename numbits "password"
The variables are:
•
•
•
For example, to generate the DSA key pair mydsakeyfile2, enter:
(config) # ssl gendsa mydsakeyfile2 512 "passwd123"Please be patient this could take a few minutesYou must also associate a DSA key pair name to the generated DSA key pair as discussed in the "Associating Certificates and Private Keys in the CSS" section of this chapter.
Generating Diffie-Hellman Key Parameters
Use the ssl gendh command to generate a Diffie-Hellman key agreement parameter file. Diffie-Hellman is a shared key agreement algorithm. Diffie-Hellman key exchange uses a complex algorithm and public/private keys to encrypt and then decrypt packet data. The CSS stores the generated Diffie-Hellman key parameter file.
Note
The syntax for this command is:
ssl gendh filename numbits "password"
The variables are:
•
•
•
For example, to generate the Diffie-Hellman key parameter list dhparamfile2, enter:
(config) # ssl gendh dhparamfile2 512 "passwd123"Please be patient this could take a few minutesYou must also associate a Diffie-Hellman parameter file name to the generated Diffie-Hellman parameter file, as discussed in the "Associating Certificates and Private Keys in the CSS" section of this chapter.
Generating a Certificate Signing Request Using an RSA Key
Use the ssl gencsr rsakey command to generate a Certificate Signing Request (CSR) file for an RSA key pair file and to transfer the certificate request to the Certificate Authority (CA). You must generate a CSR file if you are requesting a new certificate or renewing a certificate. When the CA signs the CSR, using its RSA private key, the CSR becomes the certificate.
The rsakey variable specifies the key that the RSA certificate is built on. It is the public key that is embedded in the certificate.
The RSA key pair must already be loaded on the CSS and you must associate an RSA key pair name to the generated RSA key pair (see "Associating Certificates and Private Keys in the CSS" in this chapter for details). If the appropriate key pair does not exist, the CSS logs an error message.
For example, to generate a CSR based on the RSA key pair myrsakey1, enter:
CSS11503(config)# ssl gencsr myrsakey1You are about to be asked to enter informationthat will be incorporated into your certificaterequest. What you are about to enter is what iscalled a Distinguished Name or a DN.For some fields there will be a default value,If you enter '.', the field will be left blank.Country Name (2 letter code) [US]USState or Province (full name) [SomeState]MALocality Name (city) [SomeCity]BoxboroughOrganization Name (company name) [Acme Inc]Cisco Systems, Inc.Organizational Unit Name (section) [Web Administration]Web AdminCommon Name (your domain name) [www.acme.com]www.cisco.comEmail address [webadmin@acme.com]webadmin@cisco.com-----BEGIN CERTIFICATE REQUEST-----MIIBWDCCAQICAQAwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJNQTETMBEGA1UEBxMKQm94Ym9yb3VnaDEcMBoGA1UEChMTQ2lzY28gU3lzdGVtcywgSW5jLjESMBAGA1UECxMJV2ViIEFkbWluMRYwFAYDVQQDEw13d3cuY2lzY28uY29tMSEwHwYJKoZIhvcNAQkBFhJra3JvZWJlckBjaXNjby5jb20wXDANBgkqhkiG9w0BAQEFAANLADBIAkEAqHXjtQUVXvmo6tAWPiMpe6oYhZbJUDgTxbW4VMCygzGZn2wUJTgLrifDB6N3v+1tKFndE686BhKqfyOidml3wQIDAQABoAAwDQYJKoZIhvcNAQEEBQADQQA94yC34SUJJ4UQEnO2OqRGLOZpAElc4+IV9aTWK6NmiZsM9Gt0vPhIkLx5jjhVRLlb27AkH6D5omXa0SPJan5x-----END CERTIFICATE REQUEST-----CSS11503(config)#The ssl gencsr command generates the CSR and outputs it to the screen. Most major Certificate Authorities have Web-based applications that require you to cut and paste the certificate request to the screen. Note that the CSR is not saved in the CSS.
To test your CSR file, you can create a temporary certificate by generating a CSR and signing it with your own private key. While this produces a valid certificate, most browsers flag the certificate as signed by an unrecognized signing authority. See "Generating a Self-Signed Certificate" in this chapter for details.
Generating a Self-Signed Certificate
Use the ssl gencert command to generate and save a temporary certificate to a file on disk in the CSS. For purposes of SSL testing you can generate a temporary certificate by generating a CSR and signing it with your own private key. A generated certificate is temporary and expires in 30 days.
Note
You generate the certificate by considering:
•
•
The ssl gencert command can sign RSA or DSA certificates with either an RSA key pair or a DSA key pair.
Note
The syntax for this command is:
ssl gencert certkey certkey signkey signkey certfile "password"
The variables are:
•
•
•
•
For example, to interactively generate the mycertfile2 certificate, enter:
CSS11503(config)# ssl gencert certkey myrsakey signkey myrsasignkey myrsacertfile "passwd123"You are about to be asked to enter informationthat will be incorporated into your certificaterequest. What you are about to enter is what iscalled a Distinguished Name or a DN.For some fields there will be a default value,If you enter '.', the field will be left blank.Country Name (2 letter code) [US]USState or Province (full name) [SomeState]MALocality Name (city) [SomeCity]BoxboroughOrganization Name (company name) [Acme Inc]Cisco Systems, Inc.Organizational Unit Name (section) [Web Administration]Web AdminCommon Name (your domain name) [www.acme.com]www.cisco.comEmail address [webadmin@acme.com ]webadm@cisco.comCSS11503(config)#You must also associate the contents of this temporary certificate to a filename, as discussed in the "Associating Certificates and Private Keys in the CSS" section of this chapter.
Associating Certificates and Private Keys in the CSS
After you import or generate certificate and key pair files, you must distinguish to the CSS whether these files contain certificates, private keys, or Diffie-Hellman parameters. You do this by associating certificate names, private/public key pair names, or Diffie-Hellman parameter names to the particular imported files.
When you associate the entries specified in the various certificate and private key commands to files, CSS stores the bindings in the running configuration. Before you log out or reboot the CSS, you must copy the contents of the running-config file to the startup-config file to save configuration changes and have the CSS use this configuration on subsequent reboots. When you reboot the CSS, the certificate and key associations are automatically loaded.
This section covers:
•
•
•
•
•
Associating a Certificate to a File
Use the ssl associate cert command to associate a certificate name to an imported or generated certificate. Use the no form of the command to remove the association to the file.
The syntax for this command is:
ssl associate cert certname filename
The variables are:
•
•
For example, to associate the certificate name myrsacert1 to the imported certificate file rsacert.pem, enter:
(config) # ssl associate cert myrsacert1 rsacert.pemTo remove the association to the file, enter:
(config) # no ssl associate ssl cert myrsacert1
Note
Associating an RSA Key Pair to a File
Use the ssl associate rsakey command to associate an RSA key pair name to an imported or generated RSA key pair. Use the no form of the command to remove the association to the file.
The syntax for this command is:
ssl associate rsakey keyname filename
The variables are:
•
•
For example, to associate the RSA key name myrsakey1 to the imported rsakey.pem, enter:
(config) # ssl associate rsakey myrsakey1 rsakey.pemTo remove the association to the file, enter:
(config) # no ssl associate rsakey myrsakey1
Note
Associating a DSA Key Pair to a File
Use the ssl associate dsakey command to associate a DSA key pair name to an imported or generated DSA key pair. Use the no form of the command to remove the association to the file.
The syntax for this command is:
ssl associate dsakey keyname filename
The variables are:
•
•
For example, to associate the DSA key name mydsakey1 to the imported dsakey.pem, enter:
(config) # ssl associate dsakey mydsakey1 dsakey.pemTo remove the association to the file, enter:
(config) # no ssl associate dsakey mydsakey1
Note
Associating Diffie-Hellman Parameters to a File
Use the ssl associate dhparam command to associate a Diffie-Hellman name to an imported or generated Diffie-Hellman parameter file. Use the no form of the command to remove the association to the file.
The syntax for this command is:
ssl associate dhparam paramname filename
The variables are:
•
•
For example, to associate the Diffie-Hellman file name mydhparam1 to the imported dhparams.pem, enter:
(config) # ssl associate dhparam mydhparam1 dhparams.pemTo remove the association to the file, enter:
(config) # no ssl associate dhparam mydhparam1
Note
Verifying a Certificate Against a Key Pair
A digital certificate is built around a public key, and it can only be used with one key pair. Use the ssl verify command to compare the public key in the associated certificate with the public key stored with the associated private key, and verify that they are both the same. To see a list of certificate and key pair associations, use the ssl verify ?command.
Note
The syntax for this command is:
ssl verify certname keyname
The variables are:
•
•
For example, to verify the myrsacert1 digital certificate against the myrsakey1 key pair, enter:
(config)# ssl verify myrsacert1 myrsakey1Certificate and key matchShowing Certificate and Key Pair Information
A number of show commands in the CSS enable you to display information about SSL certificates and key pairs stored on the CSS. Enter the following show commands from any mode:
•
•
•
•
•
•
Showing SSL Certificates
Use the show ssl associate cert certname command to display summary data for certificate associations in the CSS. You can optionally specify a certificate name to view detailed information about the certificate, corresponding to the certificate association. If you do not specify a certificate name, all certificate associations appear in the show ssl associate cert output.
To display information about all certificate associations:
show ssl associate certTable 9-6 describes the fields in the show ssl associate cert output.
To display information about a specific certificate association, enter:
show ssl associate cert myrsacert1Table 9-7 describes the fields in the show ssl associate cert certname output.
Showing SSL RSA Private Keys
Use the show ssl associate rsakey keyname command to obtain information about RSA private key associations in the CSS. You can optionally specify an RSA key name to view information about a specific RSA key association (key size and type). If you do not specify an RSA keyname, you see a list of all RSA key associations.
Note
To display information about all RSA private key associations:
(config) # show ssl associate rsakeyTable 9-8 describes the fields in the show ssl associate rsakey output.
To display information about a specific RSA key pair association, enter:
(config) # show ssl associate rsakey myrsakey11024-bit RSA keypairShowing SSL DSA Private Keys
Use the show ssl associate dsakey keyname command to obtain information about DSA private key associations in the CSS. You can optionally specify a DSA key name to view information about a specific DSA key association (key size and type). If you do not specify a DSA keyname, you see a list of all DSA key associations.
Note
To display information about all DSA key associations:
(config) # show ssl associate dsakeyTable 9-9 describes the fields in the show ssl associate dsakey output.
To display information about a specific DSA key pair association, enter:
(config) # show ssl associate dsakey mydsakey11024-bit DSA keypairShowing SSL Diffie-Hellman Parameters
Use the show ssl associate dhparam paramname to obtain information about Diffie-Hellman parameters. You can optionally specify a parameter file name to view information about a specific Diffie-Hellman parameter file association. If you do not specify a Diffie-Hellman parameter file name, you see a list of all Diffie-Hellman parameter file associations.
To display information about all Diffie-Hellman associations:
(config) # show ssl associate dhparamTable 9-10 describes the fields in the show ssl associate dhparam output.
To display information about a specific Diffie-Hellman parameter file association, enter:
(config) # show ssl associate dhparam mydhparam1512-bit DH parametersShowing SSL Associations
Use the show ssl associate to display a summary of all certificate and key associations stored on the CSS.
To display a summary of SSL associations for the CSS, enter:
CSS11506(config)# show ssl associateCertificate Name File Name Used by List---------------- --------- ------------rsacert rsacert.pem yesRSA Key Name File Name Used by List------------ --------- ------------rsakey rsakey.pem yesDH Param Name File Name Used by List------------- --------- ------------dhparams dhparams.pem noDSA Key Name File Name Used by List------------ --------- ------------dsakey dsakey.pem noShowing SSL Certificates, Key Pairs, and Diffie-Hellman Parameter Files
Use the show ssl files to display a list of certificates, key pairs, and Diffie-Hellman parameter files loaded on the CSS.
For example, enter:
(config) # show ssl filesTable 9-11 describes the fields in the show ssl files output.
Removing Certificates and Private Keys from the CSS
Use the clear ssl file command to remove certificates and private keys from the CSS that are no longer valid. Note that the clear ssl file command does not function if the file currently has an association with it. First remove the association to the file by specifying the no ssl associate command (see "Associating Certificates and Private Keys in the CSS" in this chapter for details).
The syntax for this global command is:
clear ssl file filename password
The variables are:
•
•
For example, to remove dsacert.pem from the CSS, enter:
# clear ssl file dsacert.pem "passwd123"Creating an SSL Proxy List
SSL termination with the CSS and initiation of HTTP connections to servers requires the use of an SSL proxy list to configure the flow of SSL information among the CSS SSL module, the client, and the server. An SSL proxy list comprises one or more virtual SSL servers (related by index entry). You can define up to 256 virtual SSL servers for a single SSL proxy list.
You add the active SSL proxy list to an ssl-accel type service to initiate the transfer of SSL configuration data for the SSL module. You add an SSL service to an SSL content rule.
For example, if the e-commerce vendor Brand New Products, Inc. wants to set up the CSS to perform SSL termination, they need to divert all traffic intended for https://www.brandnewproducts.com to the SSL module in the CSS. To do this, they must identify a VIP address for a virtual SSL server in the SSL proxy list and link the list to the same VIP of a content rule. The VIP address requires the following additional SSL configuration parameters:
•
•
•
•
•
This section describes the steps to configure an SSL proxy list, add the completed SSL proxy list to an SSL service, and add the SSL service to a content rule. It covers:
•
•
Configuring an SSL Proxy List
An SSL proxy list is a group of related virtual SSL servers that are associated with an SSL service. An SSL module in the CSS uses the virtual SSL servers to properly process and terminate SSL communications between the client and the server.
The following sections describe how to create an SSL proxy list:
•
Creating the SSL Proxy List
Use the ssl-proxy-list command to create an SSL proxy list. You can access the ssl-proxy-list configuration mode from most configuration modes except for the ACL, boot, group, rmon, or owner configuration modes. You can also use this command from the ssl-proxy-list configuration mode to access another SSL proxy list.
Enter the SSL proxy list name as an unquoted text string from 1 to 31 characters in length.
For example, to create the ssl-proxy-list ssl_list1, enter:
(config)# ssl-proxy-list ssl_list1Create ssl-list <ssl_list1>, [y/n]: yOnce you create an SSL proxy list, the CLI enters into the ssl-proxy-list configuration mode.
(ssl-proxy-list[ssl_list1])#To delete an existing ssl-proxy-list, enter:
(config)# no ssl-proxy-list ssl_list1Delete ssl-list <ssl_list1>, [y/n]: y
Note
Adding a Description to an SSL Proxy List
Use the description command to specify a description for an SSL proxy list. Enter the description as a quoted text string with a maximum of 64 characters, including spaces.
For example, to add a description to the ssl_list1 SSL proxy list, enter:
(ssl-proxy-list[ssl_list1])# description "This is the SSL list for www.brandnewproducts.com"To remove the description from a specific SSL proxy list, enter:
(ssl-proxy-list[ssl_list1])# no descriptionConfiguring Virtual SSL Servers for an SSL Proxy List
This section discusses creating one or more virtual SSL servers for a SSL proxy list. Use the ssl-server command to define an index entry in the SSL proxy list that you then use to configure specific SSL parameters associated with the SSL proxy list. An SSL module in the CSS uses the virtual SSL servers to properly process and terminate SSL communications between the client and the server. You must define an ssl-server index number before configuring ssl-proxy-list parameters. You can define up to 256 virtual SSL servers for a single SSL proxy list.
Note
The following sections describe how to create a virtual SSL server for an SSL proxy list:
•
•
•
•
•
•
•
•
•
•
•
Creating an SSL Proxy Configuration ssl-server Index
Use the ssl-server number command to identify SSL-specific parameters for the SSL proxy list. This command creates a number (index entry) in the SSL proxy list that you use to configure specific SSL parameters associated with the virtual SSL server (VIP, certificate name, key pair, and so on). You must create a virtual SSL server before you can configure SSL proxy list parameters.
Enter a value between 1 and 256 that corresponds to the SSL proxy list virtual SSL server number.
For example, to specify virtual SSL server 20, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20To remove the virtual SSL server from the SSL proxy list, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20Specifying a Virtual IP Address
Use the ssl-server number vip address ip_or_host command to specify a virtual IP (VIP) address. Enter a VIP address for the virtual SSL server that corresponds to an SSL content rule. The SSL module uses this VIP address as the means to know which traffic it should accept. Ensure that the VIP address matches a VIP address configured in a content rule. See "Configuring an SSL Content Rule" in this chapter for details.
Enter a valid VIP address in either dotted-decimal IP notation (for example, 192.168.11.1) or mnemonic host-name format (for example, myhost.mydomain.com).
Note
If the VIP address has not been defined for the virtual SSL sever when you activate the ssl-proxy-list (see "Activating an SSL Proxy List" in this chapter for details), the CSS logs an error message and does not activate the SSL proxy list. When you activate a content rule with a configured SSL service, the CSS verifies that each VIP address configured in the content rule matches at least one VIP address configured in the SSL proxy list in each of the added services. If a match is not found, the CSS logs an error message and does not activate the content rule.
For example, to specify a VIP address for the virtual SSL server that corresponds to a VIP address configured in a content rule, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 vip address 192.168.3.6To remove a VIP from a specific virtual SSL server, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 vip addressSpecifying a Virtual Port
Use the ssl-server number port number command to specify a virtual TCP port number for the virtual SSL server. Enter a TCP port number that corresponds with an SSL content rule, which uses the specified TCP port number. The SSL module uses this virtual port to know which traffic it should accept.
Specify a port number ranging from 1 to 65535. The default port is 443. Ensure that the specified port number matches the port configured in a content rule (see "Configuring an SSL Content Rule" in this chapter for details).
If the virtual port has not been defined for the virtual SSL server when you activate the ssl-proxy-list (see "Activating an SSL Proxy List" in this chapter for details), the CSS logs an error message and does not activate the SSL proxy list. When you activate a content rule with a configured SSL service, the CSS verifies that each virtual port configured in the content rule matches at least one port configured in the SSL proxy list in each of the added services. If a match is not found, the CSS logs an error message and does not activate the content rule.
For example, to specify a virtual port of 444, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 port 444To reset the virtual port to the default of 443, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 portSpecifying the RSA Certificate Name
Use the ssl-server number rsacert name command to identify the name of an RSA certificate association to be used in the exchange of a public/private key pair for authentication and packet encryption. To see a list of existing RSA certificate associations, use the ssl-server number rsacert ? command.
The specified RSA certificate must already be loaded on the CSS and an association made (see "Configuring SSL Certificates and Keys" in this chapter for details). If there is not a proper RSA certificate association, upon activation of the SSL proxy list the CSS logs an error message and does not activate the list.
For example, to specify a previously defined RSA certificate association named rsacert, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 rsacert myrsacert1To remove an RSA certificate association from a specific virtual SSL server, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 rsacertSpecifying the RSA Key Pair Name
Use the ssl-server number rsakey name command to identify the name of an RSA key pair association. RSA key pairs are a requirement before another device (client or server) can exchange an SSL certificate with the CSS. To see a list of existing RSA key pair associations, use the ssl-server number rsakey ? command.
The RSA key pair must already be loaded on the CSS and an association made (see "Configuring SSL Certificates and Keys" in this chapter for details). If there is not a proper RSA key pair association, upon activation of the SSL proxy list the CSS logs an error message and does not activate the list.
For example, to specify a previously defined RSA key pair association named rsakey, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 rsakey myrsakey1To remove an RSA key pair association from a specific virtual SSL server, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 rsakeySpecifying the DSA Certificate Name
Use the ssl-server number dsacert name command to identify the name of a DSA certificate association that is to be used in the exchange of digital signatures. To see a list of existing DSA certificate associations, use the ssl-server number dsacert ? command
The specified DSA certificate must already be loaded on the CSS and an association made (see "Configuring SSL Certificates and Keys" in this chapter for details). If there is not a proper RSA certificate association, upon activation of the SSL proxy list the CSS logs an error message and does not activate the list.
For example, to specify a previously defined DSA certificate association named dsacert, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 dsacert mydsacert1To remove a DSA certificate association from a specific virtual SSL server, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 dsacertSpecifying the DSA Key Pair Name
Use the ssl-server number dsakey name command to identify the name of a DSA key pair association. DSA key pairs are used to sign packet data, and they are a requirement before another device (client or server) can exchange an SSL certificate with the CSS. To see a list of existing DSA key pair associations, use the ssl-server number dsakey ? command.
The DSA key pair must already be loaded on the CSS and an association made (see "Configuring SSL Certificates and Keys" in this chapter for details). If there is not a proper DSA key pair association, upon activation of the SSL proxy list the CSS logs an error message and does not activate the list.
For example, to specify a previously defined DSA key pair association named dsakey, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 dsakey mydsakey1To remove a DSA key pair association from a specific virtual SSL server, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 dsakeySpecifying the Diffie-Hellman Parameter File Name
Use the ssl-server number dhparam name command to identify the name of a Diffie-Hellman key exchange parameter file association. The Diffie-Hellman key exchange parameter file ensures that the two devices in a data exchange cooperate to generate a shared key for packet encryption and authentication. To see a list of existing Diffie-Hellman key exchange parameter files, use the ssl-server number dhparam ? command.
The Diffie-Hellman parameter file must already be loaded on the CSS and an association made (see "Configuring SSL Certificates and Keys" in this chapter for details). If there is not a proper Diffie-Hellman parameter file association, upon activation of the SSL proxy list the CSS logs an error message and does not activate the list.
To specify a previously defined Diffie-Hellman parameter file association, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 dhparam mydhparams1To remove a Diffie-Hellman parameter file association from a specific virtual SSL server, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 dhparamSpecifying Cipher Suites
The SSL protocol supports a variety of different cryptographic algorithms, or ciphers, for use in operations such as authenticating the server and client to each other, transmitting certificates, and establishing session keys. Clients and servers may support different cipher suites, or sets of ciphers, depending on various factors such as the version of SSL they support, company policies regarding acceptable encryption strength, and government restrictions on export of SSL-enabled software. Among its other functions, the SSL handshake protocol determines how the server and client negotiate which cipher suites they will use to authenticate each other to transmit certificates and to establish session keys.
Note
Each cipher suite specifies a set of key exchange algorithms. Figure 9-1 summarizes the algorithms associated with the rsa-export-with-rc4-40-md5 cipher suite.
Figure 9-1 Cipher Suite Algorithms
Use the ssl-server number cipher command to assign a cipher suite for the SSL proxy list. The cipher suite that you choose must correlate to the certificates and keys that you have either imported to or generated on the CSS. For example, if you choose all-cipher-suites you must have an RSA certificate and key, a DSA certificate and key, and a Diffie-Hellman parameter file prior to activating the SSL proxy list.
For each available SSL version, there is a distinct list of supported cipher suites representing a selection of cryptographic algorithms and parameters. Your choice depends on your environment, certificates and keys in use, and security requirements. By default, no supported cipher suites are enabled.
The syntax for this command is:
ssl-server number cipher name ip_address or hostname port {weight number}
The options and variables are:
•
•
•
•
•
For example, to select the dhe-rsa-with-3des-ede-cbc-sha cipher suite with an assigned weight of 5, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 cipher dhe-rsa-with-3des-ede-cbc-sha 192.168.11.1 80 weight 5To remove a specific cipher suite from a specific virtual SSL server, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 cipher dhe-rsa-with-3des-ede-cbc-shaTable 9-12 lists all supported cipher suites and values for the specific virtual SSL server (and corresponding SSL proxy list). Table 9-12 also lists whether those cipher suites are exportable from the CSS, along with the authentication certificate and encryption key required by the cipher suite.
Caution
Cipher suites with "export" in the title indicate that they are intended for use outside of the domestic United States and that they have encryption algorithms with limited key sizes.
Specifying SSL/TLS Version
Use the ssl-server number version protocol command to specify the SSL or Transport Layer Security (TLS) protocol version. The default value is for the support of both SSL protocol version 3.0 and TLS protocol version 1.0.
The options include:
•
•
•
For example, to specify SSL version 3.0, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 version sslTo reset the SSL version to the default of SSL version 3.0 and TLS version 1.0, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 versionSpecifying SSL Session Cache Timeout
Use the ssl-server number session-cache seconds command to configure the SSL module to resume connection with a client using a previously established secret key. In SSL, a new session ID is created every time the client and the CSS SSL module go through a full key exchange and establish a new master secret key. Specifying an SSL session cache timeout allows the SSL module to reuse the master key on subsequent connections with the client, which can speed up the SSL negotiation process. You can specify a timeout value to set the total amount of time an SSL session ID remains valid before the SSL module requires the full SSL handshake to establish a new SSL connection.
The selection of an SSL session cache timeout value is important when using the advanced-balance ssl load balancing method for a Layer 5 content rule to help fine-tune the SSL session ID that is used to stick the client to the server.
Enter an SSL session cache timeout value in seconds, from 0 (SSL session ID reuse disabled) to 72000 (20 hours). The default is 300 seconds (5 minutes). By disabling this option (entering a value of 0), the full SSL handshake occurs for each new connection between the client and the SSL module.
Note
For example, to configure the reuse of an SSL session ID with a client using a timeout value of 10 hours, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 session-cache 36000To reset the SSL session reuse timeout back to 300 seconds, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 session-cacheSpecifying SSL Session Handshake Renegotiation
The SSL session handshake commands send the SSL HelloRequest message to a client to restart SSL handshake negotiation. SSL rehandshake is useful when a connection has been established for a lengthy period of time and you want to ensure security by reestablishing the SSL session.
Use the ssl-server number handshake data kbytes command to specify the maximum amount of data to be exchanged between the CSS and the client, after which the CSS transmits the SSL handshake message and reestablishes the SSL session. By setting the data value, you force the SSL session to renegotiate a new session key after a session has transferred the specified amount of data. Specify an SSL handshake data value in Kbytes, from 0 (handshake disabled) to 512000. The default is 0.
For example, to configure an SSL rehandshake message for the SSL proxy list after a data exchange of 125000 Kbytes is reached with the client, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 handshake data 125000To disable the rehandshake data option, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 handshake dataUse the ssl-server number handshake timeout seconds command to specify a maximum timeout value, after which the CSS transmits the SSL handshake message and reestablishes the SSL session. By setting a timeout value you can force the SSL session to renegotiate a new session key after a session has lasted the defined number of seconds. The selection of an SSL rehandshake timeout value is important when using the advanced-balance ssl load balancing method for a Layer 5 content rule to help fine-tune the SSL session ID used to stick the client to the server. Specify an SSL handshake timeout value in seconds, from 0 (handshake disabled) to 72000 (20 hours). The default is 0.
For example, to configure an SSL rehandshake message after a timeout value of 10 hours is reached, enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 handshake timeout 36000To disable the rehandshake timeout option, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 handshake timeout
Note
In this case, turning on SSL re-handshaking can cause SSL connections to require additional resources to perform handshake renegotiate. If you are operating in a high traffic environment, this could impact overall SSL performance.
Specifying SSL TCP Client-Side Connection Timeout Values
The TCP connection between the CSS and a client is terminated when the specified time interval expires. The TCP timeout functions enable you to have more control over the TCP connection between the CSS SSL module and a client.
To configure an SSL proxy list virtual SSL server for termination of a TCP connection with the client, refer to the following sections:
•
•
Specifying a TCP SYN Timeout Value (Client-Side Connection)
Use the ssl-server number tcp virtual syn-timeout seconds command to specify a timeout value that the CSS uses to terminate a TCP connection with a client that has not successfully completed the TCP three-way handshake prior to transferring data. The CSS SYN timer counts the delta between the CSS sending the SYN/ACK and the client replying with an ACK as the means to terminate the TCP three-way handshake.
Enter a TCP SYN inactivity timeout value in seconds, from 0 (TCP SYN timeout disabled) to 3600 (1 hour). The default is 30 seconds. When you set the command to 0, the timer becomes inactive and the retransmit timer eventually terminates a broken TCP connection.
Note
For example, to configure a TCP SYN timeout of 30 minutes (1800 seconds), enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 tcp virtual syn-timeout 1800To reset the TCP SYN timeout back to 30 seconds, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 tcp virtual syn-timeoutSpecifying a TCP Inactivity Timeout Value (Client-Side Connection)
Use the ssl-server number tcp virtual inactivity-timeout seconds command to specify a timeout value that the CSS uses to terminate a TCP connection with the client when there is little or no activity occurring on the connection. The timeout value begins once the CSS receives an ACK from the client to terminate the TCP three-way handshake. The inactivity timer resumes immediately following where the SYN timer stops, in regards to traffic flow.
Enter a TCP inactivity timeout value in seconds, from 0 (TCP inactivity timeout disabled) to 3600 (1 hour). The default is 240 seconds.
For example, to configure a TCP inactivity time of 30 minutes (1800 seconds), enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 tcp virtual inactivity-timeout 1800To reset the TCP inactivity timer back to 240 seconds, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 tcp virtual inactivity-timeoutSpecifying SSL TCP Server-Side Connection Timeout Values
The TCP connection between the CSS and a server is terminated when the specified time interval expires. The TCP timeout functions enable you to have more control over TCP connections between the CSS SSL module and a server.
To configure an SSL proxy list virtual SSL server for termination of a TCP connection with the server, refer to the following sections:
•
•
Specifying a TCP SYN Timeout Value (Server-Side Connection)
Use the ssl-server number tcp server syn-timeout seconds command to specify a timeout value that the CSS uses to abort a TCP connection with a server that has not successfully completed the TCP three-way handshake prior to transferring data. The SYN timer counts the delta between the CSS initiating the backend TCP connection by transmitting a SYN and the server replying with a SYN/ACK.
Enter a TCP SYN timeout value in seconds, from 0 (TCP SYN timeout disabled) to 3600 (1 hour). The default is 30 seconds. When you set the command to 0, the timer becomes inactive and the retransmit timer eventually terminates a broken TCP connection.
Note
For example, to configure a TCP SYN timeout of 30 minutes (1800 seconds), enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 tcp server syn-timeout 1800To reset the TCP SYN timeout back to 30 seconds, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 tcp server syn-timeoutSpecifying a TCP Inactivity Timeout Value (Server-Side Connection)
Use the ssl-server number tcp server inactivity-timeout seconds command to specify a timeout value that the CSS uses to terminate a TCP connection with a server when there is little or no activity occurring on the connection. The timeout value begins once the CSS receives a SYN/ACK from the server. The inactivity timer resumes immediately following where the SYN timer stops, in regards to traffic flow.
Enter a TCP inactivity timeout value in seconds, from 0 (TCP inactivity timeout disabled) to 3600 (1 hour). The default is 240 seconds.
For example, to configure a TCP inactivity time of 30 minutes (1800 seconds), enter:
(ssl-proxy-list[ssl_list1])# ssl-server 20 tcp server inactivity-timeout 1800To reset the TCP inactivity timer back to 240 seconds, enter:
(ssl-proxy-list[ssl_list1])# no ssl-server 20 tcp server inactivity-timeoutActivating an SSL Proxy List
Use the active command to activate the new or modified SSL proxy list. Before you can activate an SSL proxy list, ensure that you have created at least one virtual SSL server in the list (see "Configuring Virtual SSL Servers for an SSL Proxy List" in this chapter for details).
The CSS checks the SSL proxy list to verify that all of the necessary components are configured, including verification of the certificate and key pair against each other. If the verification fails, the certificate name is not accepted and the CSS logs the error message Certificate and key pair do not match and does not activate the SSL proxy list. You must either remove the configured key pair or configure an appropriate certificate.
No modifications to an SSL proxy list are permitted on an active list. Suspend the list prior to making changes, and then reactivate the SSL proxy list once the changes are complete. Once you have modified the SSL proxy list, suspend the SSL service, reactivate the SSL proxy list, then reactivate the SSL service.
To activate an SSL proxy list, enter:
(ssl-proxy-list[ssl_list1])# active
Note
Suspending the SSL Proxy List
Use the suspend command to suspend an active SSL proxy list.
To suspend an active SSL proxy list, enter:
(ssl-proxy-list[ssl_list1])# suspendAdding SSL Proxy Lists to Services
After you configure an SSL proxy list for an SSL module, add the active list to an SSL service to define how the CSS processes SSL requests for content through the specific SSL module. An SSL proxy list may belong to multiple SSL services (one SSL proxy list per service), and an SSL service may belong to multiple content rules. You can apply the services to content rules that allow the CSS to direct SSL requests for content.
Note
This section covers:
•
•
•
•
•
Creating an SSL Service for an SSL Module
When creating a service for use with an SSL module, you must identify it as an SSL service for the CSS to recognize it as such. For additional details on creating a service, refer to the Cisco Content Services Switch Basic Configuration Guide, Chapter 1, Configuring Services.
Enter the SSL service name, from 1 to 31 characters.
To create service ssl_serv1, enter:
(config)# service ssl_serv1Create service <ssl_serv1>, [y/n]: yThe CSS transitions into the newly created service mode.
Specifying the SSL Acceleration Service Type
After you create the SSL service, and the CSS enters into service mode, you must specify ssl-accel as the service type to:
•
•
Use the type command to specify the SSL acceleration service type. For details on specifying an SSL service type, refer to the Cisco Content Services Switch Basic Configuration Guide, Chapter 1, Configuring Services.
To specify the SSL acceleration service type, enter:
(config-service[ssl_serv1])# type ssl-accelSpecifying SSL Module Slot
Use the slot command to specify the slot in the CSS chassis where the SSL module is located. The 11500 series CSS supports multiple SSL modules, up to two in a CSS 11503 and up to four in a CSS 11506. The SSL service requires the SSL module slot number to correlate the SSL proxy list and virtual SSL server(s) to a specific SSL module. The valid entries are 2 and 3 (CSS 11503) or 2 to 6 (CSS 11506). Slot 1 is reserved for the SCM.
Note
For example, to identify an SSL module in slot 3 of the 11500 series CSS chassis, enter:
(config-service[ssl_serv1])# slot 3Disabling Keepalive Messages for the SSL Module
Use the keepalive type none command to instruct the CSS not to send keepalive messages to a service. The SSL module is an integrated device within the CSS chassis and, therefore, does not require the use of keepalive messages for the service. For details on specifying a keepalive type, refer to the Cisco Content Services Switch Basic Configuration Guide, Chapter 1, Configuring Services.
For disable sending keepalive messages for an SSL service, enter:
(config-service[ssl_serv1])# keepalive type noneAdding SSL Proxy Lists to a Service
Use the add ssl-proxy-list command in service mode to include an SSL proxy list as part of an SSL service. An SSL proxy list may only be added to an SSL service with ssl-accel specified as the service type. Enter the name of the previously created SSL proxy list (see "Configuring an SSL Proxy List" in this chapter for details) that you want to add to the service.
To add SSL proxy list ssl_list1 to service ssl_serv1, enter:
(config-service[ssl_serv1])# add ssl-proxy-list ssl_list1To remove the SSL proxy list from the service, enter:
(config-service[ssl_serv1])# remove ssl-proxy-list ssl_list1Specifying the SSL Session ID Cache Size
Use the session-cache-size command to reconfigure the size of the SSL session ID cache for the service. The cache size is the maximum number of SSL session IDs that can be stored in a dedicated session cache on an SSL module. By default, the SSL session cache can hold 10000 sessions. If necessary for your SSL service, you can increase the SSL session cache size to 100000. The valid entries are 0 (SSL session cache disabled) to 100000 sessions.
Note
If you specify 0 as the SSL session cache size the SSL module associated with the SSL service does not cache any SSL session IDs. If you choose to disable the SSL session cache, ensure the following are properly configured to turn off the use of SSL session ID:
•
•
For example, to specify an SSL session cache size of 20000 sessions, enter:
(config-service[ssl_serv1])# session-cache-size 20000To reset the SSL session cache size to the default of 10000 sessions, enter:
(config-service[ssl_serv1])# no session-cache-sizeActivating the SSL Service
Once you configure an SSL proxy list service, use the active command to activate the service. Activating a service puts it into the resource pool for load-balancing SSL content requests between the client and the server.
Before activating an SSL service:
•
•
Once the service is ready to activate, the CSS initiates the transfer of appropriate SSL configuration data for each SSL proxy list to a specific SSL module and activates the service. If there is an error in transfer, the CSS logs the appropriate error and does not activate the service.
No modifications may be made to an active SSL proxy list. If modifications are necessary, first suspend the ssl service to make changes to the SSL proxy list entries.
To activate service ssl_serv1, enter:
(config-service[ssl_serv1])# activeSuspending the SSL Service
Use the suspend command to suspend an SSL service and remove it from the pool for future load-balancing SSL content requests. Suspending an SSL service does not affect existing content flows, but it prevents additional connections from accessing the service for its content.
You must suspend a service prior to modifying an SSL proxy list.
To suspend service ssl_serv1, enter:
(config-service[ssl_serv1])# suspendConfiguring an SSL Content Rule
To configure a content rule, add one or more SSL services, and activate the content rule, refer to the Cisco Content Services Switch Basic Configuration Guide, Chapter 3, Configuring Content Rules. No network traffic is sent to an SSL module until you activate an SSL content rule to define where the content physically resides, where to direct the request for content (which SSL service), and which load-balancing method to use.
Ensure that each VIP address and port configured in the content rule matches a VIP address and port configured in one of the SSL proxy list entries in an associated SSL service. When you activate a content rule with a configured SSL service, the CSS verifies that there is a match. If a match is not found, the CSS logs the error message Not all content VIP:Port combinations are configured in an ssl-proxy-list for sslAccel type of service and does not activate the content rule. Verify the configured VIP addresses used in the content rule and SSL proxy list, and modify as necessary.
When using two or more SSL modules, Cisco Systems recommends that you use stickiness based on SSL version 3 session ID for a Layer 5 content rule specify the following in the content rule:
•
•
The Layer 5 SSL sticky content rule ensures SSL session ID reuse to eliminate the rehandshake process (which speeds up the SSL negotiation process) and to increase overall performance.
Note
Note
Showing SSL Proxy Configuration Information
Use the show ssl-proxy-list command to display information about SSL proxy lists. You can display general information about all SSL proxy lists or detailed information about a specific SSL proxy list.
You can enter the show ssl-proxy-list commands from the specified command modes to display configuration information for an SSL proxy list:
•
–
–
•
•
•
To view general information about all configured SSL proxy lists, enter:
# show ssl-proxy-listTable 9-13 describes the fields in the show ssl-proxy-list output.
To display detailed configuration information about ssl_list1 from the ssl-proxy-list mode, enter:
(ssl-proxy-list[ssl_list1])# show ssl-proxy-listTo display detailed configuration information about ssl_list1 from the global configuration mode, enter:
(config)# show ssl-proxy-list ssl_list1Table 9-14 describes the fields in the show ssl-proxy-list list_name output.
Table 9-14 Field Descriptions for the show ssl-proxy-list list_name
CommandDescription
The description for the SSL proxy list
Number of SSL Proxy ssl-servers
The total number of virtual SSL servers specified for the SSL proxy list
ssl-server
A unique number for the virtual SSL server
VIP Address
The VIP for the virtual SSL server number (corresponding to an SSL proxy list)
VIP Port
The virtual TCP port for the virtual SSL server number (corresponding to an SSL proxy list)
RSA Certificate
The name of the RSA certificate
RSA Keypair
The name of the RSA key
DSA Certificate
The name of the DSA certificate
DSA Keypair
The name of the DSA key pair
DH Param
The name of the Diffie-Hellman parameter association
Session Cache Timeout
The period of time an SSL session ID remains valid before the CSS requires the full SSL handshake to establish a new SSL connection
SSL Version
The specified SSL (version 3.0), TLS (version 1.0), or SSL and TLS protocol in use
Rehandshake Timeout
The period of time the CSS waits before initiating an SSL rehandshake message
Rehandshake Data
The maximum amount of data to be exchanged between the CSS and the client, after which the CSS transmits the SSL handshake message and reestablishes the SSL session
Virtual TCP Inactivity Timeout
The time period that the CSS waits before terminating a TCP connection with a client when there is little or no activity occurring on the connection
Virtual TCP Syn Timeout
The time period that the CSS waits before terminating a TCP connection with a client that has not successfully completed the TCP three-way handshake with the CSS prior to transferring data
Server TCP Inactivity Timeout
The time period that the CSS waits before terminating a TCP connection with a server when there is little or no activity occurring on the connection
Server TCP Syn Timeout
The time period that the CSS waits before terminating a TCP connection with a server that has not successfully completed the TCP three-way handshake with the CSS prior to transferring data
Cipher Suite(s)
The name of the cipher suite(s) assigned to the SSL content rule (see Table 9-12)
Weight
The priority assigned to the cipher suite
Port
The TCP port of the backend content rule/server through which the backend HTTP connections are sent
Server
The IP address assigned to the backend content rule/server used with the cipher suite
Showing SSL Statistics
Use the show ssl statistics command to view the statistics for the cryptography components on one or more SSL modules. If you do not specify any options for this command, SSL statistics appear for all SSL modules in the CSS chassis.
The syntax for this command is:
show ssl statistics {component} {slot number}
The options and variables are:
•
–
–
–
•
For example, to view all SSL statistics for the SSL module in slot 5 of the CSS chassis, enter:
# show ssl statistics slot 5Table 9-15 describes the fields in the show ssl statistics output.
Clearing SSL Statistics
Use the clear ssl statistics command to clear the SSL statistics counters for all SSL modules in the CSS chassis. The reset statistics appear as 0 in the show ssl statistics display.
To clear SSL statistics counters for a specific module, use the clear ssl statistics command and specify the slot number following the command. The valid slot entries are 2 and 3 (CSS 11503) or 2 to 6 (CSS 11506).
To clear the SSL statistics counter, enter:
# clear ssl statisticsShowing SSL Flows
Use the show ssl flows command to display information about the active flows for each VIP address, port, and SSL module. The output displays TCP proxy flows, active SSL flows (a subset of TCP proxy flows), and SSL flows occurring during the handshake phase of the protocol (a subset of active SSL flows).
The syntax for this command is:
show ssl flows {slot number}
The slot number option displays information about the active flows for a specific SSL module in the CSS chassis (assuming more than one module is installed). The valid slot entries are 2 and 3 (CSS 11503) or 2 to 6 (CSS 11506). If no slot number is specified, the show ssl flows command displays statistics for all installed SSL modules.
To view SSL flows for all SSL modules in the CSS, enter:
# show ssl flowsTo view SSL flows for a specific SSL module in the CSS chassis (for example, installed in slot 5), enter:
# show ssl flows slot 5Table 9-16 describes the fields in the show ssl flows output.
Example SSL Proxy Configurations
This section describes the SSL flow process with the SSL module and includes example proxy configurations. Each configuration section includes a running-configuration example and an accompanying illustration.
This section covers:
•
•
•
•
Processing of SSL Flows by the SSL Module
To terminate SSL flows, the SSL module functions as a proxy server, which means that it is the TCP endpoint for inbound SSL traffic. The SSL module maintains a separate TCP connection for each side of the communications, the client side and the server side. The proxy server can perform both TCP and SSL handshakes.
The following example is intended as an overview on the flow process; how the CSS and SSL module translate flows from HTTPS-to-HTTP for inbound packets and from HTTP-to-HTTPS for outbound packets. Figure 9-2 illustrates a CSS with three SSL modules (M1, M2, and M3) configured to off load the SSL traffic from the backend servers (ServerABC, ServerDEF, and ServerGHI). Figure 9-2 also shows the CSS maintaining a consistent stickiness between HTTP and SSL connections from the same client.
1.
Figure 9-2 CSS Configuration with Multiple SSL Modules
2.
3.
4.
5.
6.
Multiple TCP connections can comprise an entire SSL session. For each of those connections, the same process takes place among the client, SSL module, and server. The SSL Session ID maintains the stickiness between the client and the SSL module and the cookie maintains the stickiness between the SSL module and the servers. In this way, stickiness can be maintained consistently through the entire web transaction.
Note
SSL Transparent Proxy Configuration - One SSL Module
An SSL transparent proxy server is a proxy server that preserves the client's IP address as the source IP address for the backend connection to the server. When you configure an SSL transparent proxy on the CSS, the CSS intercepts and redirects outbound client requests to an HTTP server on the network without changing the source IP address.
This section provides a simple configuration of an SSL transparent proxy between a client, a CSS with a single SSL module, and three HTTP servers (ServerABC, ServerDEF, and ServerGHI). Two content rules are used in this configuration, an SSL content rule and a HTTP content rule. The SSL content rule is for Layer 4 because there is only a single SSL module and there is no need to maintain client-to-server (SSL) stickiness. The use of a Layer 4 content rule in this configuration may improve CSS performance.
Figure 9-3 illustrates this transparent proxy configuration.
For purposes of illustration, the configuration example in Figure 9-3 shows the VIP address for the SSL content rule (ssl-rule) to be the same as the VIP address for the HTTP content rul e (http-rule). These two VIPs do not have to be identical. Depending on the method that you choose to allow access to secure content on your HTTP servers, you may require specification of a different VIP for the clear-text content rule to place it in non-routable address space. In this example, instead of specifying a VIP address of 192.27.5.5 for the http-rule content rule, you could specify a VIP address of 10.1.1.5. The clear-text http-rule will be unreachable from the Internet, which can offer you more flexibility and granularity while allowing the CSS to be seamlessly integrated for secure transactions.
Figure 9-3 Transparent Proxy Configuration with a Single SSL Module
!*************************** GLOBAL ***************************logging commands enablessl associate dsakey dsakey dsakey.pemssl associate dhparam dhparams dhparams.pemssl associate rsakey rsakey rsakey.pemssl associate cert rsacert rsacert.pemftp-record ssl_record 161.44.174.127 anonymous des-password deye2gtcld1b6feeeebabfcfagyezc5f /!************************** CIRCUIT **************************circuit VLAN1ip address 192.4.8.254 255.255.255.0circuit VLAN2ip address 192.4.7.254 255.255.255.0!*********************** SSL PROXY LIST ***********************ssl-proxy-list testssl-server 111ssl-server 111 vip address 192.27.5.5ssl-server 111 port 443ssl-server 111 rsacert rsacertssl-server 111 rsakey rsakeyssl-server 111 cipher rsa-with-rc4-128-md5 192.27.5.5 80active!************************** SERVICE **************************service ssl_module1type ssl-accelkeepalive type noneslot 5add ssl-proxy-list testactiveservice serverABCip address 192.4.7.1protocol tcpport 80keepalive type httpactiveservice serverDEFip address 192.4.7.2protocol tcpport 80keepalive type httpactiveservice serverGHIip address 192.4.7.3protocol tcpport 80keepalive type httpactive!*************************** OWNER ***************************owner ap.comcontent ssl-rulevip address 192.27.5.5protocol tcpport 443add service ssl_module1activecontent http-rulevip address 192.27.5.5protocol tcpport 80add service serverABCadd service serverDEFadd service serverGHIadvanced-balance cookiesactiveSSL Transparent Proxy Configuration - Two SSL Modules
This section provides an example configuration for an SSL transparent proxy between a client, a CSS with two SSL modules, and three HTTP servers (ServerABC, ServerDEF, and ServerGHI). A Layer 5 SSL sticky content rule is used in the configuration to maintain stickiness of the client to a particular SSL module. The Layer 5 SSL sticky content rule ensures SSL session ID reuse to eliminate the rehandshake process (which speeds up the SSL negotiation process) and to increase overall performance.
Figure 9-4 illustrates this transparent proxy configuration.
For purposes of illustration, the configuration example in Figure 9-4 shows the VIP address for the SSL content rule (ssl-rule) to be the same as the VIP address for the HTTP content rul e (http-rule). These two VIPs do not have to be identical. Depending on the method that you choose to allow access to secure content on your HTTP servers, you may require specification of a different VIP for the clear-text content rule to place it in non-routable address space. In this example, instead of specifying a VIP address of 192.27.5.5 for the http-rule content rule, you could specify a VIP address of 10.1.1.5. The clear-text http-rule will be unreachable from the Internet, which can offer you more flexibility and granularity while allowing the CSS to be seamlessly integrated for secure transactions.
Figure 9-4 Transparent Proxy Configuration with Two SSL Modules
!*************************** GLOBAL ***************************logging commands enablessl associate dsakey dsakey dsakey.pemssl associate rsakey rsakey rsakey.pemssl associate cert rsacert rsacert.pemssl associate dhparam dhparams dhparams.pemftp-record ssl_record 161.44.174.127 anonymous des-password deye2gtcld1b6feeeebabfcfagyezc5f /!************************** CIRCUIT **************************circuit VLAN1ip address 192.4.8.254 255.255.255.0circuit VLAN2ip address 192.4.7.254 255.255.255.0!*********************** SSL PROXY LIST ***********************ssl-proxy-list testssl-server 111ssl-server 111 vip address 192.27.5.5ssl-server 111 rsacert rsacertssl-server 111 rsakey rsakeyssl-server 111 cipher rsa-with-rc4-128-md5 192.27.5.5 80ssl-server 111 port 443active!************************** SERVICE **************************service ssl_module1type ssl-accelkeepalive type noneslot 5add ssl-proxy-list testactiveservice ssl_module2type ssl-accelkeepalive type noneslot 6add ssl-proxy-list testactiveservice serverABCip address 192.4.7.1protocol tcpport 80keepalive type httpactiveservice serverDEFip address 192.4.7.2protocol tcpport 80keepalive type httpactiveservice serverGHIip address 192.14.7.3protocol tcpport 80keepalive type httpactive!*************************** OWNER ***************************owner ap.comcontent ssl-rulevip address 192.27.5.5protocol tcpport 443add service ssl_module1add service ssl_module2application ssladvanced-balance sslactivecontent http-rulevip address 192.27.5.5protocol tcpport 80url "/*"add service serverABCadd service serverDEFadd service serverGHIadvanced-balance cookiesactiveSSL Full Proxy Configuration - One SSL Module
An SSL full proxy server is a proxy server that terminates the client's SSL connections and initiates the backend connection to the HTTP server using a different source IP address than of the client. This configuration does not preserve the client's IP address for the backend connection to the HTTP server.
This section provides an example configuration for an SSL full proxy between a client, a CSS with a single SSL module, and three HTTP servers (ServerABC, ServerDEF, and ServerGHI). A Layer 5 sticky content rule is used in the configuration. For the CSS to implement a full proxy configuration with an SSL module, the configuration includes a source group that is used to isolate the SSL module traffic and to NAT its source address.
Figure 9-5 illustrates this full proxy configuration.
For purposes of illustration, the configuration example in Figure 9-5 shows the VIP address for the SSL content rule (ssl-rule) to be the same as the VIP address for the HTTP content rul e (http-rule). These two VIPs do not have to be identical. Depending on the method that you choose to allow access to secure content on your HTTP servers, you may require specification of a different VIP for the clear-text content rule to place it in non-routable address space.
In this example, instead of specifying a VIP address of 192.168.5.5 for the http-rule content rule, you could specify a VIP address of 10.1.1.5. The clear-text http-rule will be unreachable from the Internet, which can offer you more flexibility and granularity while allowing the CSS to be seamlessly integrated for secure transactions.
Figure 9-5 Full Proxy Configuration Using a Single SSL Module
!*************************** GLOBAL ***************************logging commands enablessl associate dsakey dsakey dsakey.pemssl associate dhparams dhparams dhparams.pemssl associate rsakey rsakey rsakey.pemssl associate cert rsacert rsacert.pemftp-record ssl_record 161.44.174.127 anonymous des-password deye2gtcld1b6feeeebabfcfagyezc5f /!************************** CIRCUIT **************************circuit VLAN1ip address 192.168.5.254 255.255.255.0circuit VLAN2ip address 192.168.7.254 255.255.255.0!*********************** SSL PROXY LIST ***********************ssl-proxy-list testssl-server 111ssl-server 111 vip address 192.168.5.5ssl-server 111 port 443ssl-server 111 rsacert rsacertssl-server 111 rsakey rsakeyssl-server 111 cipher rsa-with-rc4-128-md5 192.168.5.5 80active!************************** SERVICE **************************service ssl_module1type ssl-accelkeepalive type noneslot 5add ssl-proxy-list testactiveservice ssl_module2type ssl-accelkeepalive type noneslot 6add ssl-proxy-list testactiveservice serverABCip address 192.168.7.1protocol tcpport 80keepalive type httpactiveservice serverDEFip address 192.168.7.2protocol tcpport 80keepalive type httpactiveservice serverGHIip address 192.168.7.3protocol tcpport 80keepalive type httpactive!*************************** OWNER ***************************owner ap.comcontent ssl-rulevip address 192.168.5.5protocol tcpport 443add service ssl_module1add service ssl_module2application ssladvanced-balance sslactivecontent http-rulevip address 192.168.5.5protocol tcpport 80url "/*"add service serverABCadd service serverDEFadd service serverGHIadvanced-balance cookiesactive!*************************** GROUP ***************************group ssl_module_proxyadd destination service serverABCadd destination service serverDEFadd destination service serverGHIvip address 192.168.7.200active
