Storing PKI Credentials

Public key infrastructure (PKI) credentials, such as Rivest, Shamir, and Adelman (RSA) keys and certificates can be stored in a specific location on the router, such as NVRAM and flash memory or on a USB eTtoken 64 KB smart card. USB tokens provide secure configuration distribution, RSA operations such as on-token key generation, signing, and authentication, and the storage of Virtual Private Network (VPN) credentials for deployment.

Finding Feature Information

Your software release may not support all the features documented in this module. For the latest caveats and feature information, see
Bug Search Tool and the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the feature information table at the end of this module.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to
www.cisco.com/​go/​cfn. An account on Cisco.com is not required.

Prerequisites for Storing PKI Credentials

Prerequisites for Specifying a Local Certificate Storage Location

Before you can specify the local certificate storage location, your system should meet the following requirements:

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

Prerequisites for Specifying USB Token Storage for PKI Credentials

Before you can use a USB token, your system should meet the following requirements:

PKI Credentials and USB Tokens

How a USB Token Works

A smart card is a small plastic card, containing a microprocessor and memory that allows you to store and process data. A USB token is a smart card with a USB interface. The token can securely store any type of file within its available storage space (32 KB). Configuration files that are stored on the USB token can be encrypted and accessed only via a user PIN. The device does not load the configuration file unless the proper PIN has been configured for secure deployment of device configuration files.

After you plug the USB token into the device, you must log into the USB token; thereafter, you can change default settings, such as the user PIN (default: 1234567890) and the allowed number of failed login attempts (default: 15 attempts) before future logins are refused. For more information on accessing and configuring the USB token, see the section “Logging Into and Setting Up the USB Token."

After you have successfully logged into the USB token, you can copy files from the device on to the USB token via the
copy command. USB token RSA keys and associated IPsec tunnels remain available until the device is reloaded. To specify the length of time before the keys are removed and the IPsec tunnels are torn down, issue the
cryptopkitokenremovaltimeout command. The default timeout is zero, which causes the RSA keys to be removed automatically after the eToken is removed from the device. The default appears in the running configuration as:

crypto pki token default removal timeout 0

The table below highlights the capabilities of the USB token.

Table 1 Functionality Highlights for USB Tokens

Function

USB Token

Accessibility

Used to securely store and transfer digital certificates, preshared keys, and device configurations from the USB token to the device.

The device can use the configuration stored in the USB token during boot time.

The device can use the secondary configuration stored in the USB token during boot time. (A secondary configuration allows users to load their IPsec configuration.)

Benefits of USB Tokens

USB token support on a Cisco router provides the following application benefits:

Removable Credentials: Provide or Store VPN Credentials on an External Device for Deployment

A USB token can use smart card technology to store a digital certificate and configuration for IPsec VPN deployment. This ability enhances the capability of the router to generate RSA public keys to authenticate at least one IPsec tunnel. (Because a router can initiate multiple IPsec tunnels, the USB token can contain several certificates, as appropriate.)

PIN Configuration for Secure File Deployment

A USB token can store a configuration file that can be used for enabling encryption on the router via a user-configured PIN. (That is, no digital certificates, preshared keys, or VPNs are used.)

Touchless or Low Touch Configuration

The USB token can provide remote software configuration and provisioning with little or no human interaction. Configuration is set up as an automated process. That is, the USB token can store a bootstrap configuration that the router can use to boot from after the USB token has been inserted into the router. The bootstrap configuration connects the router to a TFTP server, which contains a configuration that completely configures the router.

RSA Operations

A USB token may be used as a cryptographic device in addition to a storage device. Using a USB token as a cryptographic device allows RSA operations such as key generation, signing, and authentication to be performed on the token.

General-purpose, special-usage, encryption, or signature RSA key pairs with a modulus of 2048 bits or less may be generated from credentials located on your token storage device. Private keys are not distributed and remain on the token by default, however you may configure the private key storage location.

Keys that reside on a USB token are saved to persistent token storage when they are generated. Key deletion will remove the keys stored on the token from persistent storage immediately. (Keys that do not reside on a token are saved to or deleted from non-token storage locations when the
writememory or a similar command is issued.)

SDP may be used to configure a USB token. The configured USB token may be transported to provision a device at a remote location. That is, a USB token may be used to transfer cryptographic information from one network device to another remote network device providing a solution for a staged USB token deployment.

For information about using USB tokens with SDP, see document titles in the “Additional References” section.

Configuring the Device for Manual Login

Manual login can be used when storing a PIN on the device is not desirable. Manual login may also be suitable for some initial deployment or hardware replacement scenarios for which the device is obtained from the local supplier or drop-shipped to the remote site. Manual login can be executed with or without privileges, and it creates files and RSA keys on the USB token available to the Cisco IOS software. If a secondary configuration file is configured, it is executed only with the privileges of the user who is performing the login. Thus, if you want to use manual login and set up the secondary configuration on the USB token to perform anything useful, you need to enable privileges.

Manual login can also be used in recovery scenarios for which the device configuration has been lost. If the scenario contains a remote site that normally connects to the core network with a VPN, the loss of the configuration and RSA keys requires out-of-band services that the USB token can provide. The USB token can contain a boot configuration, a secondary configuration, or both, and RSA keys to authenticate the connection.

SUMMARY STEPS

1.enable

2.crypto pki tokentoken-name [admin]
login [pin]

3. show usbtoken0-9:filename

DETAILED STEPS

Command or Action

Purpose

Step 1

enable

Example:

Device> enable

Enables privileged EXEC mode.

Enter your password if prompted.

Step 2

crypto pki tokentoken-name [admin]
login [pin]

Example:

Device# crypto pki token usbtoken0 admin login 5678

Manually logs into the USB token.

If the
admin keyword is not specified initially you can re-enter the
crypto pki token command again with this keyword option.

Step 3

show usbtoken0-9:filename

Example:

Device# show usbtoken0:usbfile

(Optional) Verifies whether the USB token has been logged on to the device.

What to Do Next

After you have logged into the USB token, it is available for use.

To further configure the USB token, see the “Configuring the USB Token” section.

To perform USB token administrative tasks, such as changing the user PIN, copying files from the router to the USB token set key storage location, and changing USB tokens, see the “Setting Administrative Functions on the USB Token” section.

Configuring the USB Token

After you have set up automatic login, you may perform this task to further configure the USB token.

PINs and Passphrases

For additional PIN security with automatic login, you may encrypt your PIN stored in NVRAM and set up a passphrase for your USB token. Establishing a passphrase allows you to keep your PIN secure; another user needs only to know the passphrase, not the PIN.

When the USB token is inserted into the device, the passphrase is needed to decrypt the PIN. Once the PIN is decrypted, the device can then use the PIN to log in to the USB token.

Note

The user needs a privilege level of 1 to log in.

Unlocking and Locking the USB Token

The USB token itself can be locked (encrypted) or unlocked (decrypted).

Unlocking the USB token allows it to be used. Once unlocked, Cisco IOS software treats the token as if it were automatically logged in. Any keys on the USB token are loaded, and if a secondary configuration file is on the token, it is executed with full user privileges (privilege level 15) independent of the privilege level of the logged-in user.

Locking the token, unlike logging out of the token, deletes any RSA keys loaded from the token and runs the secondary unconfiguration file, if configured.

Secondary Configuration and Unconfiguration Files

Configuration files that exist on a USB token are called secondary configuration files. If you create and configure a secondary configuration file, it is executed after the token is logged in. The existence of a secondary configuration file is determined by the presence of a secondary configuration file option in the Cisco IOS configuration stored in NVRAM. When the token is removed or logged out and the removal timer expires, a separate secondary unconfiguration file is processed to remove all secondary configuration elements from the running configuration. Secondary configuration and secondary unconfiguration files are executed at privilege level 15 and are not dependent on the level of the user logged in.

SUMMARY STEPS

1.enable

2.cryptopkitokentoken-nameunlock [pin]

3.configureterminal

4.cryptopkitokentoken-nameencrypted-user-pin [write]

5.cryptopkitokentoken-namesecondaryunconfigfile

6.exit

7.cryptopkitokentoken-namelock [pin]

DETAILED STEPS

Command or Action

Purpose

Step 1

enable

Example:

Device> enable

Enables privileged EXEC mode.

Enter your password if prompted.

Step 2

cryptopkitokentoken-nameunlock [pin]

Example:

Device# crypto pki token mytoken unlock mypin

(Optional) Allows the token to be used if the USB token has been locked.

Once unlocked, Cisco IOS software treats the token as if it has been automatically logged in. Any keys on the token are loaded and if a secondary configuration file exists, it is executed.

The following example shows a how a secondary unconfiguration file might be used to remove secondary configuration elements from the running configuration. For example, a secondary configuration file might be used to set up a PKI trustpoint. A corresponding unconfiguration file, named mysecondaryunconfigfile.cfg, might contain this command line:

no crypto pki trustpoint token-tp

If the token were removed and the following commands executed, the trustpoint and associated certificates would be removed from the device’s running configuration:

What to Do Next

After you have logged into and configured the USB token, it is available for use. If you want to perform USB token administrative tasks, such as changing the user PIN, copying files from the router to the USB token set key storage location, and changing USB tokens, see the “Setting Administrative Functions on the USB Token” section.

Setting Administrative Functions on the USB Token

Perform this task to change default settings, such as the user PIN, the maximum number of failed attempts on the USB token, or the credential storage location.

When specifying a label name by specifying the
key-label argument, you must use the same name for the label that you plan to use for the certificate server (through the
crypto pki servercs-label command). If a
key-label argument is not specified, the default value, which is the fully qualified domain name (FQDN) of the device, is used.

If the exportable RSA key pair is manually generated after the CA certificate has been generated, and before issuing the
noshutdown command, then use the
cryptocaexportpkcs12 command to export a PKCS12 file that contains the certificate server certificate and the private key.

By default, the modulus size of a CA key is 1024 bits. The recommended modulus for a CA key is 2048 bits. The range for a modulus size of a CA key is from 350 to 4096 bits.

The
on keyword specifies that the RSA key pair is created on the specified device, including a Universal Serial Bus (USB) token, local disk, or NVRAM. The name of the device is followed by a colon (:).

(Optional) Moves existing Cisco IOS credentials from the current storage location to the specified storage location.

By default, the RSA key pair remains stored on the current device.

Generating the key on the device and moving it to the token takes less than a minute. Generating a key on the token, using the
on keyword could take five to ten minutes, and is dependent on hardware key generation routines available on the USB token.

When an existing RSA key pair is generated in Cisco IOS, stored on a USB token, and used for an enrollment, it may be necessary to move those existing RSA key pairs to an alternate location for permanent storage.

This command is useful when using SDP with USB tokens to deploy credentials.

Step 8

crypto pki token {token-name |
default}
removal timeout [seconds]

Example:

Device(config)# crypto pki token usbtoken0 removal timeout 60

(Optional) Sets the time interval, in seconds, that the device waits before removing the RSA keys that are stored in the USB token after the USB token has been removed from the device.

Note

If this command is not issued, all RSA keys and IPsec tunnels associated with the USB token are torn down immediately after the USB token is removed from the device.

Step 9

crypto pki token {token-name |
default}
max-retries [number]

Example:

Device(config)# crypto pki token usbtoken0 max-retries 20

(Optional) Sets the maximum number of consecutive failed login attempts allowed before access to the USB token is denied.

By default, the value is set at 15.

Step 10

exit

Example:

Device(config)# exit

Exits global configuration mode.

Step 11

copy usbflash[0-9]:filenamedestination-url

Example:

Device# copy usbflash0:file1 nvram:

Copies files from USB token to the device.

destination-url—See the
copy command page documentation for a list of supported options.

Step 12

show usbtoken[0-9]:filename

Example:

Device# show usbtoken:usbfile

(Optional) Displays information about the USB token. You can use this command to verify whether the USB token has been logged in to the device.

Step 13

crypto pki tokentoken-namelogout

Example:

Device# crypto pki token usbtoken0 logout

Logs the device out of the USB token.

Note

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

Troubleshooting USB Tokens

This section contains descriptions of the following Cisco IOS commands that can be used to help troubleshoot possible problems that may arise while using a USB token:

Troubleshooting the USB Port Connection

Use the
show file systems command to determine whether the router recognizes that there is a USB module plugged into a USB port. The USB module should appear on the list of file systems. If the module does not appear on the list, it can indicate any of the following problems:

A connection problem with the USB module.

The Cisco IOS image running on the router does not support a USB module.

A hardware problem with the USB module itself.

Sample output from the
show file systems command showing a USB token appears below. The USB module listing appears in the last line of the examples.

Determining if a USB Token is Supported by Cisco

Use the
show usb device command to determine if a USB token is supported by Cisco. The following output from this command indicates whether or not the module is supported is bold in the sample output below:

Determining USB Token Device Problems

Use the
showusbcontrollers command to determine if there is a hardware problem with a USB flash module. If the
showusbcontrollers command displays an error, the error indicates a hardware problem in the USB module.

You can also use the
showusbcontrollers command to verify that copy operations onto a USB flash module are occurring successfully. Issuing the
showusbcontrollers command after performing a file copy should display successful data transfers.

The following sample output for theshowusbcontrollers command displays a working USB flash module:

The following sample output from the
showcryptokeymypubkeyrsa command displays stored credentials after they are successfully loaded from the USB token. Credentials that are stored on the USB token are in the protected area. When storing the credentials on the USB token, the files are stored in a directory called /keystore. However, the key files are hidden from the command-line interface (CLI).

See the “Configuring Certificate Enrollment or Autoenrollment” section of the “Configuring Certificate Enrollment for a PKI ” feature document.

SDP setup, configuration and use with USB tokens

See the feature information section for the feature names on using SDP and USB tokens to deploy PKI credentials in the “Setting Up Secure Device Provisioning (SDP) for Enrollment in a PKI” feature document.

Technical Assistance

Description

Link

The Cisco Support and Documentation website provides online resources to download documentation, software, and tools. Use these resources to install and configure the software and to troubleshoot and resolve technical issues with Cisco products and technologies. Access to most tools on the Cisco Support and Documentation website requires a Cisco.com user ID and password.

Feature Information for Storing PKI Credentials

The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to
www.cisco.com/​go/​cfn. An account on Cisco.com is not required.

Table 2 Feature Information for Storing PKI Credentials

Feature Name

Releases

Feature Information

USB Token and Secure Device Provisioning (SDP) Integration

12.4(15)T

This feature provides the ability to provision remote devices with USB tokens using SDP.

The following sections in this document provide information about this feature:

Benefits of USB Tokens

Setting Administrative Functions on the USB Token

The following commands were introduced by this feature:
binary file,
cryptokeymoversa,
templatefile.

Note

This document introduces the benefits of using USB tokens and SDP for a deployment solution.

Cisco IOS USB Token PKI Enhancements -- Phase 2

12.4(11)T

This feature enhances USB token functionality by using the USB token as a cryptographic device. USB tokens may be used for RSA operations such as key generation, signing, and authentication.

The following sections in this document provide information about this feature:

Benefits of USB Tokens

Logging Into and Setting Up the USB Token

Setting Administrative Functions on the USB Token

Note

This document introduces the benefits of using USB tokens and the keys on the token for RSA operations.

USB Storage PKI Enhancements

12.4(4)T

12.4(11)T

This feature enhances the USB token PIN security for automatic login and increases the flexibility of USB token configuration and the RSA key storage.

The following commands were introduced or modified by this feature:
cryptokeystorage,
cryptopkigeneratersa,cryptopkitokenencrypted-user-pin,
cryptopkitokenlabel,
cryptopkitokenlock,
cryptopkitokensecondaryunconfig,
cryptopkitokenunlock

Certificate -- Storage Location Specification

12.2(33)SXH

12.2(33)SRA

12.4(2)T

This feature allows you to specify the storage location of local certificates for platforms that support storing certificates as separate files. All Cisco platforms support NVRAM, which is the default location, 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.

The following sections provide information about this feature:

Storing Certificates to a Local Storage Location

Specifying a Local Storage Location for Certificates

Storing Certificates to a Specific Local Storage Location Example

The following commands were introduced by this feature:
cryptopkicertificatestorage,
showcryptopkicertificatesstorage