Usage Guidelines

This command is required when you initially configure CA support at your router.

This command authenticates the CA to your router by obtaining the self-signed certificate of the CA that contains the public key of the CA. Because the CA signs its own certificate, you should manually authenticate the public key of the CA by contacting the CA administrator when you enter this command.

If you are using Router Advertisements (RA) mode (using the enrollment command) when you issue the crypto pki authenticate command, then registration authority signing and encryption certificates will be returned from the CA and the CA certificate.

This command is not saved to the router configuration. However. the public keys embedded in the received CA (and RA) certificates are saved to the configuration as part of the Rivest, Shamir, and Adelman (RSA) public key record (called the “RSA public key chain”).

Note

If the CA does not respond by a timeout period after this command is issued, the terminal control will be returned so that it remains available. If this happens, you must reenter the command. Cisco IOS software will not recognize CA certificate expiration dates set for beyond the year 2049. If the validity period of the CA certificate is set to expire after the year 2049, the following error message will be displayed when authentication with the CA server is attempted: error retrieving certificate :incomplete chain If you receive an error message similar to this one, check the expiration date of your CA certificate. If the expiration date of your CA certificate is set after the year 2049, you must reduce the expiration date by a year or more.

Usage Guidelines

Use the crypto pki benchmark start command to start the collection of PKI benchmarking performance monitoring and optimization data. Use the crypto pki benchmark stop command to stop the collection of the PKI benchmarking performance monitoring and optimization data.

Use the show crypto pki benchmarks command to view the collection data.

Use the clear crypto pki benchmarks command to clear the PKI benchmarking performance monitoring and optimization data and release all memory associated with this data.

The IOS PKI Performance Monitoring and Optimization feature enables you to collect the following types of PKI performance data:

• Time to validate entire certificate chain.

• Time to verify each certificate.

• Time to check revocation status for each certificate.

• Time to fetch certificate revocation list (CRL) database for each fetch location.

• Time to fetch Simple Certificate Enrollment Protocol (SCEP) method capabilities to retrieve the CRL.

• Time to process each CRL.

• Time to process the Online Certificate Status Protocol (OCSP) response. OCSP is a certificate revocation mechanism.

• Time to fetch Authentication, Authorization, and Accounting (AAA).

• CRL size.

• Validation result.

• Validation Bypass (pubkey cached).

• Method used to fetch a CRL.

• PKI session identifier.

• Crypto engine used (hardware, software, etoken).

Usage Guidelines

The crypto pki cert validate command validates the router's own certificate for a given trustpoint. Use this command as a sanity check after enrollment to verify that the trustpoint is properly authenticated, a certificate has been requested and granted for the trustpoint, and that the certificate is currently valid. A certificate is valid if it is signed by the trustpoint certification authority (CA), not expired, and so on.

Usage Guidelines

This command puts you into certificate chain configuration mode. When you are in certificate chain configuration mode, you can delete certificates using the certificate command.

You need to be in certificate chain configuration mode to delete certificates.

Usage Guidelines

Issuing this command places the router in ca-certificate-map configuration mode where you can specify several certificate fields together with their matching criteria. The general form of these fields is as follows:

field-name match-criteria match-value

The field-name field in the above example is one of the certificate fields. Field names are similar to the names used in the ITU-T X.509 standard. The field-name is a special field that matches any subject name or related name field in the certificate, such as the alt-subject-name, subject-name , and unstructured-subject-name fields.

• alt-subject-name -- Case-insensitive string.

• expires-on --Date field in the format dd mm yyyy hh:mm:ss or mmm dd yyyy hh:mm:ss.

• issuer-name -- Case-insensitive string.

• name -- Case-insensitive string.

• serial-number--Case-insensitive string.

• subject-name --Case-insensitive string.

• unstructured-subject-name -- Case-insensitive string.

• valid-start --Date field in the format dd MM. yyy hh:mm:ss or mmm dd yyyy hh:mm:ss.

Note

For Yang environment, the date and time format for both the expires-on date and valid-start- field follow the same format. The string UTC should always be appended to the date and time as in yang environment the time is only accepted as Universal Time, Coordinated (UTC). expires-on -- Case sensitive string. Date field in the format mmm dd yyyy hh:mm:ss UTC. valid-start -- Case sensitive string. Date field in the format mmm dd yyyy hh:mm:ss UTC.

Note

The time portion is optional in both the expires-on date and valid-start field and defaults to 00:00:00 if not specified. The time is interpreted according to the time zone offset configured for the router. The string utc can be appended to the date and time when they are configured as Universal Time, Coordinated (UTC) rather than local time.

The match-criteria field in the example is one of the following logical operators:

• eq --equal (valid for name and date fields)

• ne --not equal (valid for name and date fields)

• co --contains (valid only for name fields)

• nc --does not contain (valid only for name fields)

• lt --less than (valid only for date fields)

• ge --greater than or equal to (valid only for date fields)

The match-value field is a case-insensitive string or a date.

Usage Guidelines

Normally, certain certificates are stored locally in the router’s NVRAM, and each certificate uses a moderate amount of memory. To save NVRAM space, you can use this command to put the router into query mode, preventing certificates from being stored locally; instead, they are retrieved from a specified CA trustpoint when needed. This will save NVRAM space but could result in a slight performance impact.

The crypto pki certificate query command is a subcommand for each trustpoint; thus, this command can be disabled on a per-trustpoint basis.

Before you can configure this command, you must enable the crypto pki trustpoint command , which puts you in ca-trustpoint configuration mode.

Note	This command deprecates the crypto ca certificate query command in global configuration mode. Although you can still enter the global configuration command, the configuration mode and command will be written back as ca-trustpoint.

Usage Guidelines

All Cisco platforms support NVRAM and flash local storage. Depending on your platform, you may have other supported local storage options including bootflash, slot, disk, USB flash, or USB token.

During run time, you can specify what active local storage device you would like to use to store PKI credentials. You must have the following system requirements before you can specify PKI credentials local storage location:

• A Cisco IOS Release 12.4(2)T PKI-enabled image or a later image

• A platform that supports storing PKI credentials as separate files

• A configuration that contains at least one certificate

• An accessible local file system

When using a local storage device to store PKI data, the following restrictions are applicable:

• Only local file systems may be used. An error message will be displayed if a remote file system is selected, and the command will not take effect.

• A subdirectory may be specified if supported by the local file system. NVRAM does not support subdirectories.

• Settings will take effect only when the running configuration is saved to the startup configuration.

If the keys are generated on the etoken, then the default storage loaction for the certificates is the etoken

for the device certificates. The CA certificates are stored in NVRAM. This allows for the credentials(keysa nd certificates) to be stored together on the removable media by default.

Usage Guidelines

The CRL cache is a global cache that holds all CRLs downloaded by the router regardless of the trustpoint configuration. The impact on router memory depends upon the CRL cache size configured by the administrator. Configuring the CRL cache size allows the amount of memory used for the CRL cache to be reduced (for instance, if low memory conditions exist) or to be increased for better performance (for instance, when a large number of CRLs are being processed).

If the crypto pki crl cache command is issued, regardless of the CRL cache size value set, the CRL cache size will be included in the configuration. Issuing the no crypto pki crl cache command will remove the CRL cache size from the configuration.

When a CRL is stored in the CRL cache, it is condensed at least one-fifth of its original size. Therefore, more CRLs can be stored in the CRL cache than would be expected based on the CRL size before being cached.

Note

To configure CRL caching for a given trustpoint, you may issue either the crl-cache none or crl cache delete-after command. To disable caching of CRLs for a given trustpoint, use the crl-cache none command. To set a maximum age for CRLs in the cache for a given trustpoint, use the crl cache delete-after command.

Usage Guidelines

A CRL lists all the certificates of the network device that have been revoked. Revoked certificates will not be honored by your router; therefore, any IPSec device with a revoked certificate cannot exchange IP Security traffic with your router.

The first time your router receives a certificate from a peer, it will download a CRL from the CA. Your router then checks the CRL to make sure the certificate of the peer has not been revoked. (If the certificate appears on the CRL, it will not accept the certificate and will not authenticate the peer.)

A CRL can be reused with subsequent certificates until the CRL expires. If your router receives the certificate of a peer after the applicable CRL has expired, it will download the new CRL.

If your router has a CRL which has not yet expired, but you suspect that the contents of the CRL are out of date, use the crypto pki crl request command to request that the latest CRL be immediately downloaded to replace the old CRL.

This command is not saved to the configuration.

Note	This command should be used only after the trustpoint is enrolled.

Usage Guidelines

This command requests certificates from the CA for all of your router’s Rivest, Shamir, and Adelmen (RSA) key pairs. This task is also known as enrolling with the CA. (Technically, enrolling and obtaining certificates are two separate events, but they both occur when this command is issued.)

Your router needs a signed certificate from the CA for each RSA key pairs of your router; if you previously generated general-purpose keys, this command obtains the one certificate corresponding to the one general-purpose RSA key pair. If you previously generated special-usage keys, this command obtains two certificates corresponding to each of the special-usage RSA key pairs.

If you already have a certificate for your keys you are prompted to remove the existing certificate first. (You can remove existing certificates with the no certificate command.)

The crypto pki enroll command is not saved in the router configuration.

Note	If your router reboots after you issue the crypto pki enroll command but before you receive the certificates, you must reissue the command.

Note

If you are using a Secure Shell (SSH) service, you should set up specific RSA key pairs (different private keys) for the trustpoint and the SSH service. (If the Public Key Infrastructure [PKI] and the SSH infrastructure share the same default RSA key pair, a temporary disruption of SSH service could occur. The RSA key pair could become invalid or change because of the CA system, in which case you would not be able to log in using SSH. You could receive the following error message: “key changed, possible security problem.”)

Responding to Prompts

When you issue the crypto pki enroll command, you are prompted a number of times.

You are prompted to create a challenge password. This password can be up to 80 characters in length. This password is necessary in the event that you ever need to revoke your router’s certificates. When you ask the CA administrator to revoke your certificate, you must supply this challenge password as a protection against fraudulent or mistaken revocation requests.

Note	This password is not stored anywhere, so you need to remember this password.

If you lose the password, the CA administrator may still be able to revoke the router’s certificate but will require further manual authentication of the router administrator identity.

You are also prompted to indicate whether your router’s serial number should be included in the obtained certificate. The serial number is not used by IP Security (IPsec) or Internet Key Exchange, but may be used by the CA to either authenticate certificates or to later associate a certificate with a particular router. (Note that the serial number stored is the serial number of the internal board, not the one on the enclosure.) Ask your CA administrator if serial numbers should be included. If you are in doubt, include the serial number.

Normally, you would not include the IP address because the IP address binds the certificate more tightly to a specific entity. Also, if the router is moved, you would need to issue a new certificate. A router has multiple IP addresses, any of which might be used with IPsec.

If you indicate that the IP address should be included, you will then be prompted to specify the interface of the IP address. This interface should correspond to the interface that you apply your crypto map set to. If you apply crypto map sets to more than one interface, specify the interface that you name in the crypto map local-address command.

Usage Guidelines

Note	Security threats, as well as the cryptographic technologies to help protect against them, are constantly changing. For more information about the latest Cisco cryptographic recommendations, see the Next Generation Encryption (NGE) white paper.

The crypto pki export pem command allows you to export certificate and RSA key pairs in PEM-formatted files. The PEM files can then be imported back into the Cisco IOS router (via the crypto pki import pem command) or other public key infrastructure (PKI) applications.

The RSA keys in PEM-formatted files can be exported from the following source URL file systems:

Usage Guidelines

Public-key cryptography standards were devised and published by RSA Security. A PKCS12 file has a format commonly used to store private keys with accompanying public key certificates that is protected with a password-based symmetric key. The crypto pki export pkcs12 password command creates a PKCS12 file that contains an RSA key pair. The PKCS12 file, along with a certificate authority (CA), is exported to the location that you specify with the destination URL. If you decide not to import the file to another router, you must delete the file.

Security Measures

Keep the PKCS12 file stored in a secure place with restricted access.

An RSA key pair is more secure than a password phrase because the private key in the key pair is not known by multiple parties. When you export an RSA key pair to a PKCS12 file, the RSA key pair now is only as secure as the password phrase.

To create a good password phrase, be sure to include numbers, as well as both lowercase and uppercase letters. Avoid publicizing the password phrase by mentioning it in e-mail or cell phone communications because the information could be accessed by an unauthorized user.

The RSA keys can be exported from the following destination URL file systems:

Usage Guidelines

The crypto pki http max-buffer-size command enables you to set the maximum http receive buffer for PKI. By default, the http max-buffer size is 10MB. You can increase this value till 100MB and reduce the value till 1MB by using this command.

It is recommended that you set the max-buffer-size only when you see the following error displayed during PKI transactions: (debug crypto pki transaction) “CRYPTO_PKI: HTTP Payload is more than the allowed buffer size”.

Usage Guidelines

You must enter the crypto pki import command twice if usage keys (signature and encryption keys) are used. The first time the command is entered, one of the certificates is pasted into the router; the second time the command is entered, the other certificate is pasted into the router. (It does not matter which certificate is pasted first.)

Usage Guidelines

The crypto pki import pem command allows certificates and RSA key pairs in PEM-formatted files to be imported. The files can be previously exported from another router or generated from other public key infrastructure (PKI) applications.

The RSA keys in PEM-formatted files can be imported from the following source URL file systems:

Usage Guidelines

When you enter the crypto pki import pkcs12 password command, a key pair and a trustpoint are generated.

If the key pair and trustpoint that were generated need to be removed, then enter the crypto key zeroize rsa command to zeroize the key pair and enter the no crypto pki trustpoint command to remove the trustpoint.

Note	After you import RSA keys to a target router, you cannot export those keys from the target router to another router.

The RSA keys can be imported from the following source URL file systems:

Usage Guidelines

Before entering this command, you must specify a named enrollment profile using the enrollment profile in ca-trustpoint configuration mode.

After entering the crypto pki profile enrollment command, you can use any of the following commands to define the profile parameters:

• authentication command --Specifies the HTTP command that is sent to the certification authority (CA) for authentication.

• authentication terminal --Specifies manual cut-and-paste certificate authentication requests.

• authentication url --Specifies the URL of the CA server to which to send authentication requests.

• enrollment command --Specifies the HTTP command that is sent to the CA for enrollment.

• enrollment terminal --Specifies manual cut-and-paste certificate enrollment.

• enrollment url --Specifies the URL of the CA server to which to send enrollment requests.

• parameter --Specifies parameters for an enrollment profile. This command can be used only if the authentication command or the enrollment command is used.

Note	The authentication url , enrollment url , authentication terminal , and enrollment terminal commands allow you to specify different methods for certificate authentication and enrollment, such as TFTP authentication and manual enrollment.

Usage Guidelines

Once the crypto pki server command is entered, the certificate server configuration mode commands can be configured to deploy the public key infrastructure (PKI) by defining the default behavior of the CS, which limits user interface complexity. See the Related Commands section for more information on these commands.

Note	All CS-related commands are optional; therefore any basic CS functionality that is not specified through the CLI for these commands uses their default value.

• issuer-name -- Specifies the distinguished name (DN) as the CA issuer name for the certificate server.

• lifetime (certificate server) --Specifies the lifetime of the CA or a certificate.

• lifetime crl --Defines the lifetime of the certificate revocation list (CRL) that is used by the certificate server.

• shutdown --Allows a certificate server to be disabled without removing the configuration.

Automated CA Certificate Rollover

CAs and their clients, have certificates with expiration dates that have to be reissued when the current certificate is about to expire. CAs also have key pairs used to sign client certificates. When the CA certificate is expiring it must generate a new certificate and possibly a new key pair. This process, called rollover, allows for continuous operation of the network while clients and the certificate server are switching from an expiring CA certificate to a new CA certificate.

Usage Guidelines

After you enable the crypto pki server grant command, your certificate server will immediately grant all specified certificate requests. Certificate requests that are not granted will expire after the time that was specified using the lifetime enrollment-request command.

Usage Guidelines

CRLs are issued once every specified time period via the lifetime crl command. It is the responsibility of the network administrator to ensure that the CRL is available from the location that is specified via the cdp-url command. To access information, such as the lifetime and location of the CRL, use the crypto pki server info crl command.

Usage Guidelines

A certificate enrollment request functions as follows:

• The certificate server receives the enrollment request from an end user, and the following actions occur:

  • A request entry is created in the enrollment request database with the initial state. (See the show pki server command for a complete list of certificate enrollment request states.)
  • The certificate server refers to the command-line interface (CLI) configuration (or the default behavior any time a parameter is not specified) to determine the authorization of the request. Thereafter, the state of the enrollment request is updated in the enrollment request database.
• At each Simple Certificate Enrollment Protocol (SCEP) query for a response, the certificate server examines the current request and performs one of the following actions:

  • Responds to the end user with a “pending” or “denied” state.
  • Forwards to the request to the certification authority (CA) core, where it will generate and sign the appropriate certificate, store the certificate in the enrollment request database, and return the request to the built-in certificate server SCEP server, who will reply to the end user with the certificate on the next SCEP request.

If the connection of the client has closed, the certificate server will wait for client user to request another certificate.

All enrollment requests transitions through the certificate enrollment states that are defined in the table below.

Usage Guidelines

SCEP, which is the only supported enrollment protocol, supports two client authentication mechanisms--manual and preshared key. Manual enrollment requires the administrator at the certification authority (CA) server to specifically authorize the enrollment requests; enrollment using preshared keys allows the administrator to preauthorize enrollment requests by generating a one-time password.

Note	Only one password is valid at a time; if a second password is generated, the previous password is no longer valid.

Usage Guidelines

After you enable the crypto pki server reject command, your certificate server will immediately reject all certificate requests.

SCEP, which is the only supported enrollment protocol, supports two client authentication mechanisms--manual and preshared key. Manual enrollment requires the administrator at the certification authority (CA) server to specifically authorize the enrollment requests. The administrator can become overloaded if there are numerous enrollment requests. Thus, the crypto pki server reject command can be reduce user interaction by automatically rejecting all or specific enrollment requests.

Usage Guidelines

After the certificate server receives an enrollment request, it can leave the request in pending, reject it, or grant it. Before this command was added, the request would be left in the Enrollment Request Database for 1 hour until the client polled the certficiate server for the result of the request. This command allows you to remove individual or all requests from the database, especially useful if the client leaves and never polls the certificate server.

In addition, the use of this command also allows the server to be returned to a clean slate with respect to the keys and transaction IDs. Thus, it is a useful command to use during troubleshooting with a Simple Certificate Enrollment Protocol (SCEP) client that may be behaving badly.

Usage Guidelines

Use the crypto pki server request pkcs10 command to manually add a base64-encoded, PEM-formatted, or hexadecimal-encoded PKCS10 certificate enrollment request. This command is especially useful when the client does not have a network connection with the certificate server so that it can do Simple Certificate Enrollment Protocol (SCEP) enrollment. After the certificate is granted, the certificate will be displayed on the console terminal using base64 encoding if the terminal keyword is specified, or it will be sent to the file system that is specified using the url argument.

The url argument allows you to specify or change the location in which the certificate server retrieves the new certificate request and posts the granted certificate. The table below lists available file system options.

Usage Guidelines

When a new certificate revocation list (CRL) is issued, the certificate server obtains the previous CRL, makes the appropriate changes, and resigns the new CRL. A new CRL is issued after a certificate is revoked from the CLI. If this process negatively affects router performance, the crypto pki server revoke command can be used to revoke a list or range of certificates.

Note	In Cisco IOS Release 15.0(1)M, the serial number to be revoked is not compared with the last-issued serial number.

Note	A new CRL cannot be issued unless the current CRL is revoked or changed.

Usage Guidelines

Using the crypto pki server start command is the same as using the no shut command in DSP configuration mode.

Usage Guidelines

Using the crypto pki server stop command is the same as using the shutdown command in DSP configuration mode.

Usage Guidelines

This command trims expired certificates from the CRL. Only certificates that are expired and have accurate and complete information in the certificate database can be trimmed from the database.

Depending on the size and location of the certificate database, searching the database for expired certificates may be a time-consuming process. Depending on your environment, you may choose one of three methods to search and to trim your CRL:

• Search the entire certificate database.

This is usually the most time-consuming and resource-consuming method.

• Specify a range of certificate serial numbers to search.

If a large number of certificates are in your certificate database or if your certificate database is stored at a remote location (for example, TFTP or Secure Copy [SCP]) you may limit the range of certificates to search by specifying both the starting and ending certificate serial numbers. If no starting and ending certificate serial numbers are specified, the entire certificate database will be searched and all expired certificates will be trimmed.

• Use an input list to specify the expired certificates to be trimmed from the CRL.

This is the most scalable method because it divides the process into two steps: searching the certificate database for expired certificates and trimming the CRL. An input file listing expired certificate serial numbers may be generated using a Perl script or similar program, manually, or by issuing the crypto pki server trim generate expired-list command. The input list must follow the format as shown:

# CRL Trimming file generated on 01/31/2008
version=1
35
37

Lines that begin with a pound sign (#) are inserted comments. The second line contains a version string indicating the file type. Each remaining line (in this example lines 35 and 37) contains a certificate serial number indicating one certificate to be removed from the CRL.

Usage Guidelines

This command generates a list of expired certificates that are in the CRL for the specified certificate server. The resulting list of expired certificates may be used as input to the crypto pki server trim command to remove the listed certificates from the CRL resulting in trimming, or revoking, the expired certificates.

Only certificates that have accurate and complete information in the certificate database can be automatically added to the list of expired certificates and later trimmed from the database. Only CRL entries for expired certificates can be trimmed.

If there are a large number of certificates in your certificate database or if your certificate database is stored at a remote location, for example TFTP or SCP, you may limit the range of certificates to search by specifying both the starting and ending certificate serial numbers. If no starting and ending certificate serial numbers are specified, the entire certificate database will be searched and all expired certificates will be added to the expired certificates list.

A URL may be specified to save the list of expired certificates to a specified location. If no URL is specified, the list of expired certificates will be printed on your terminal. The list may then be cut and pasted to a file.

Usage Guidelines

If a certificate is erroneously revoked, either the client has to reenroll in the PKI or the administrator may recover the revoked certificate by issuing the crypto pki server unrevoke command. This command removes a certificate, specified by its serial number, from the CRL. The CRL is then resigned and can be republished.

Usage Guidelines

If you want to change the administrative PIN on the token, you must be logged into the eToken as an admin via the crypto pki token admin login command.

After the user PIN has been changed, you must reset the login failure count to zero (via the crypto pki token max-retries command). The maximum number of allowable login failures is set (by default) to 15.

Usage Guidelines

After the token’s PIN is encrypted with the crypto pki token encrypted-user-pin command, no action is taken when you insert the token into the router. The user must log in to the router and enter the passphrase to decrypt the PIN before the router can use the PIN to log in to the token.

After the PIN has been successfully decrypted, the router will execute the configuration commands from the token at privilege level 15.

Tip	It is recommended that you create a passphrase different from the token’s PIN. Also, the user should log in to the token as a “normal user” (a privilege level 1 user), so the user cannot access commands that can alter the configuration of the router.

Usage Guidelines

After you have logged in your USB token to the router, you may want to change the factory default label. Changing the default factory name to a unique name is useful when configuring multiple USB tokens for automatic login, secondary configuration files, or other token specific settings.

Note	Either the device name or label may be used to specify the USB token. If using the device name, it is followed by a colon, “:”.

Usage Guidelines

After you have locked a token with the crypto pki token lock command, all Rivest, Shamir, and Adelman (RSA) keys that have been loaded from the token will be deleted and, if configured, the secondary “unconfig” file will run with full privileges.

Usage Guidelines

This command allows you to manually log into a USB eToken. To automatically log into an eToken, issue the crypto pki token user-pin command, which allows you to create a PIN for automatic login.

Usage Guidelines

If you want to save any data to the USB eToken, you must log back into the eToken.

Usage Guidelines

After the user PIN is changed via the crypto pki token c hange-pin command , the login failure count is automatically reset to 15; however, it is recommended that the login failure count be set to zero.

Usage Guidelines

After the eToken is removed from the router, you can clear from your router any RSA keys that were obtained from the eToken; all IPSec tunnels that used those RSA keys for authentication are also torn down. Both the keys and tunnels are immediately cleared unless otherwise specified via the crypto pki token removal timeout command.

Although the RSA keys remain on the eToken, they can only be accessed with the correct PIN. Too many unsuccessful attempts to log into the eToken will disable the PIN and any further login attempts will be refused.

Note	The no version of this command does not remove RSA keys from the router. To immediately remove RSA keys from the router, set the timeout value to zero.