11.5 Managing PKCS#11 Tokens

A PKCS#11 token is a software or hardware interface to a Public-Key Cryptography Standards (PKCS) 11-compliant security database in which digital certificates and keys can be stored. Oracle Traffic Director includes a token named internal that provides the interface to the built-in Network Security Services (NSS) certificate database. If any other PKCS#11-compliant databases are available on the administration server host, Oracle Traffic Director recognizes them automatically and exposes the corresponding tokens, including those implemented through physical devices like hardware accelerators and smart cards.

Note:

The information in this section is aimed at readers who are familiar with the concepts of SSL, certificates, ciphers, and keys. For basic information about those concepts, see Section 11.2.7, "SSL/TLS Concepts."

You can enable and disable initialization of PKCS#11 tokens for a Oracle Traffic Director configuration and enable the pins for the tokens.

If initialization of PKCS#11 tokens is enabled for a configuration and if the pin is enabled for any of the tokens, when you attempt to start instances of the configuration, a prompt to enter the pins for pin-enabled tokens is displayed.

To avoid having to enter the token pin every time you start instances, while specifying the pin, you can opt to save it in the configuration file, as described later in this section.
If the pin is enabled for a token in a configuration, when you access the certificates database represented by that token for any purpose (for example, to view installed certificates or to install a certificate), a prompt to select the token and enter the token pin is displayed. To avoid having to enter the token pin repeatedly, you can cache it as described in "Caching the Token Pins for an Administration Console Session".

You can configure PKCS#11 tokens by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Section 2.3.1, "Accessing the Command-Line Interface."

Configuring PKCS#11 Settings Using the Administration Console

To configure a PKCS#11 token by using the administration console, do the following:

Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to configure tokens.
In the navigation pane, select SSL.

The SSL Settings page is displayed. The Cryptographic Tokens section contains the parameters pertaining to PKCS#11 tokens.
- To enable initialization of PKCS#11 tokens, select the PKCS#11 Tokens check box.
- If you want Oracle Traffic Director to bypass processing of the PKCS#11 layer during SSL/TLS processing, select the Allow PKCS#11 Bypass check box. Bypassing the PKCS#11 layer improves performance.
- To enable or disable a token, and to set or change a token's pin, click on the token name.
  
  The Edit Token dialog box is displayed.
  - To enable the token, select the Token State check box.
  - To enable the token pin, select the Set Token Pin check box.
    
    Enter the new pin and confirm it.
  - To change the token pin, select the Edit Token Pin check box.
    
    Enter the current pin, and then enter the new pin and confirm it.
  - To disable the token pin, select the Edit Token Pin check box.
    
    Enter the current pin, and then select the Unset Pin check box.
Note:
- If you select Save Pin, the token pin is saved in the configuration file. Users are not prompted to enter the token pin when they attempt to start instances of the configuration.
- If you set or change the token pin, and choose not to save it in the configuration file, then to restart the server, you should stop it and then start it again. You cannot restart the server by using the restart-admin CLI command or through the administration console.
When you change the value in a field or tab out of a text field that you changed, the Save button is enabled.
After making the required changes, click Save.
- A message, confirming that the updated configuration was saved, is displayed in the Console Messages pane.
- In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Section 4.3, "Deploying a Configuration."

Configuring PKCS#11 Settings Using the CLI

To enable or disable initialization of PKCS#11 tokens, run the set-pkcs11-prop command, as shown in the following example:
```
tadm> set-pkcs11-prop --config=soa enabled=true
OTD-70201 Command 'set-pkcs11-prop' ran successfully.
```

To view the available PKCS#11 tokens in a configuration, run the list-tokens commands as shown in the following example:

tadm> list-tokens --config=soa --verbose --all
name            enabled         has-saved-pin
---------------------------------------------
internal        false           false

To enable or disable a token, run the set-token-prop command, as shown in the following example:

tadm> set-token-prop --config=soa --token=internal enabled=true
OTD-70201 Command 'set-token-prop' ran successfully.

To set or change the pin for a token, run the set-token-pin command, as shown in the following example:
```
tadm> set-token-pin --config=soa --token=internal
```
If the token is already protected with a pin, a prompt to enter the current pin is displayed. Enter the current pin, and when prompted, enter the new pin and confirm it.

Note:

If you enable initialization of PKCS#11 tokens (set-pkcs11-prop ... enabled=true) and if the pin is enabled for any of the tokens, then when you attempt to start or restart the instances of the configuration, a prompt to enter the pins for the pin-enabled tokens is displayed. To suppress the pin prompt, you can save the pins in the configuration file by specifying the --save-pin=true option for the set-token-pin command.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Caching the Token Pins for an Administration Console Session

If the pin is enabled for a token in a configuration, when you access the certificates database represented by that token for any purpose (for example, to view installed certificates or to install a certificate), a prompt to select the token and enter the token pin is displayed. When using the administration console for managing certificates, you can avoid having to enter the token pins repeatedly, by specifying them once and caching them for the duration of the session; that is until you log out or until the session times out.

To cache the token pins for an administration-console session, do the following:

Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to cache token pins.
In the navigation pane, expand SSL and select Server Certificates or Certificate Authorities.
Click Cache Token Pin.

The Cache Token Pin dialog box is displayed.
Enter the pins for the tokens.
Click OK.

A message is displayed in the Console Messages pane confirming that the token pins are cached for the session.