Managing Certificates in Oracle Solaris

4 Managing Certificates in Oracle Solaris

The Key Management Framework (KMF) feature of Oracle Solaris provides tools and programming interfaces for managing public key objects. Public key objects include X.509 certificates and public/private key pairs. The formats for storing these objects can vary. KMF also provides a tool for managing policies that define the use of X.509 certificates by applications. KMF supports third-party plugins. Key management can require manual intervention, such as adding CA certificates to the directory where Oracle Solaris stores them.

This chapter covers the following topics:

Managing Public Key Technologies With the Key Management Framework

KMF centralizes the management of public key technologies (PKI). Oracle Solaris has several different applications that make use of PKI technologies. Each application provides its own programming interfaces, key storage mechanisms, and administrative utilities. If an application provides a policy enforcement mechanism, the mechanism applies to that application only. With KMF, applications use a unified set of administrative tools, a single set of programming interfaces, and a single policy enforcement mechanism. These features manage the PKI needs of all applications that adopt these interfaces.

KMF unifies the management of public key technologies with the following interfaces:

pktool command – Manages PKI objects, such as certificates, in a variety of keystores.
kmfcfg command – Manages the PKI policy database and third-party plugins.

PKI policy decisions include operations such as the validation method for an operation. Also, PKI policy can limit the scope of a certificate. For example, PKI policy might assert that a certificate can be used only for specific purposes. Such a policy would prevent that certificate from being used for other requests.
KMF library – Contains programming interfaces that abstract the underlying keystore mechanism.

Applications do not have to choose one particular keystore mechanism, but can migrate from one mechanism to another mechanism. The supported keystores are PKCS #11, NSS, and OpenSSL. The library includes a pluggable framework so that new keystore mechanisms can be added. Therefore, applications that use the new mechanisms would require only minor modifications to use a new keystore.

Key Management Framework Utilities

KMF provides methods for managing the storage of keys and provides the overall policy for the use of those keys. KMF can manage the policy, keys, and certificates for three public key technologies:

Tokens from PKCS #11 providers, that is, from the Cryptographic Framework
NSS, that is, Network Security Services
OpenSSL, a file-based keystore

The kmfcfg tool can create, modify, or delete KMF policy entries. The tool also manages plugins to the framework. KMF manages keystores through the pktool command. For more information, see the kmfcfg(1) and pktool(1) man pages, and the following sections.

KMF Policy Management

KMF policy is stored in a database. This policy database is accessed internally by all applications that use the KMF programming interfaces. The database can constrain the use of the keys and certificates that are managed by the KMF library. When an application attempts to verify a certificate, the application checks the policy database. The kmfcfg command modifies the policy database.

KMF Plugin Management

The kmfcfg command provides the following subcommands for plugins:

list plugin – Lists plugins that are managed by KMF.
install plugin – Installs the plugin by the module's path name and creates a keystore for the plugin. To remove the plugin from KMF, you remove the keystore.
uninstall plugin – Removes the plugin from KMF by removing its keystore.
modify plugin – Enables the plugin to be run with an option that is defined in the code for the plugin, such as debug.

For more information, see the kmfcfg(1) man page. For the procedure, see How to Manage Third-Party Plugins in KMF.

KMF Keystore Management

KMF manages the keystores for three public key technologies, PKCS #11 tokens, NSS, and OpenSSL. For all of these technologies, the pktool command enables you to do the following:

Generate a self-signed certificate
Generate a certificate request
Generate and configure a token
Generate a symmetric key
Generate a public/private key pair
Generate a PKCS #10 certificate signing request (CSR) to be sent to an external certificate authority (CA) to be signed
Sign a PKCS #10 CSR
Import objects into the keystore
List the objects in the keystore
Delete objects from the keystore
Download a CRL

For the PKCS #11 and NSS technologies, the pktool command also enables you to set a PIN by generating a passphrase for the keystore or for an object in the keystore.

For examples of using the pktool utility, see the pktool(1) man page and Using the Key Management Framework Task Map.

Using the Key Management Framework

This section describes how to use the pktool command to manage your public key objects, such as passwords, passphrases, files, keystores, certificates, and CRLs.

The Key Management Framework (KMF) enables you to centrally manage public key technologies.

Table 4-1 Using the Key Management Framework Task Map

Task	Description	For Instructions
Create a certificate.	Creates a certificate for use by PKCS #11, NSS, or OpenSSL.	How to Create a Certificate by Using the pktool gencert Command
Export a certificate.	Creates a file with the certificate and its supporting keys. The file can be protected with a password.	How to Export a Certificate and Private Key in PKCS #12 Format
Import a certificate.	Imports a certificate from another system.	How to Import a Certificate Into Your Keystore
Import a certificate.	Imports a certificate in PKCS #12 format from another system.	How to Import a Certificate Into Your Keystore
Create a keystore or token.	Creates a token, assigns a PIN, and names a label.	How to Create a PKCS #11 Keystore
Generate a passphrase.	Generates a passphrase for access to a PKCS #11 keystore or an NSS keystore.	How to Generate a Passphrase by Using the pktool setpin Command
Generate a symmetric key.	Generates symmetric keys for use in encrypting files, in creating a MAC of a file, and for applications.	How to Generate a Symmetric Key by Using the pktool Command
Generate a key pair.	Generates a public/private key pair for use with applications.	How to Generate a Key Pair by Using the pktool genkeypair Command
Generate a PKCS #10 CSR.	Generates a PKCS #10 certificate signing request (CSR) for an external certificate authority (CA) to sign.	pktool(1) man page
Sign a PKCS #10 CSR.	Signs a PKCS #10 CSR.	How to Sign a Certificate Request by Using the pktool signcsr Command
Add a plugin to KMF.	Installs, modifies, and lists a plugin. Also, removes the plugin from the KMF.	How to Manage Third-Party Plugins in KMF

How to Create a Certificate by Using the pktool Command

This procedure creates a self-signed certificate and stores the certificate in the PKCS #11 keystore. As a part of this operation, an RSA public/private key pair is also created. The private key is stored in the keystore with the certificate.

Generate a self-signed certificate.
```
$ pktool gencert [keystore=keystore] label=label-name \
subject=subject-DN serial=hex-serial-number keytype=rsa/dsa keylen=key-size
```
‐keystore=keystore

Specifies the keystore by type of public key object. The value can be nss, pkcs11, or file. This keyword is optional.

‐label=label-name

Specifies a unique name that the issuer gives to the certificate.

‐subject=subject-DN

Specifies the distinguished name for the certificate.

‐serial=hex-serial-number

Specifies the serial number in hexadecimal format. The issuer of the certificate chooses the number, such as 0x0102030405.

‐keytype=key type

Optional variable that specifies the type of private key associated with the certificate. Check the pktool(1) man page to find available key types for the selected keystore.

To use a FIPS 140-2 approved key, check the approved key types at FIPS 140-2 Algorithms in the Cryptographic Framework in Using a FIPS 140-2 Enabled System in Oracle Solaris 11.4.

‐keylen=key size

Optional variable that specifies the length of the private key associated with the certificate.

To use a FIPS 140-2 approved key, check the approved key lengths for the key type that you selected at FIPS 140-2 Algorithms in the Cryptographic Framework in Using a FIPS 140-2 Enabled System in Oracle Solaris 11.4.
keystoreslisting contentslistingcontents of keystorepktool commandlist subcommandlist subcommandpktool commandVerify the contents of the keystore.
```
$ pktool list
Found number certificates.
1. (X.509 certificate)
Label:  label-name
ID: fingerprint that binds certificate to private key
Subject: subject-DN
Issuer:  distinguished-name
Serial:  hex-serial-number
n. ...
```
This command lists all certificates in the keystore. In the following example, the keystore contains one certificate only.

Example 4-1 Creating a Self-Signed Certificate by Using pktool

In the following example, a user at My Company creates a self-signed certificate and stores the certificate in a keystore for PKCS #11 objects. The keystore is initially empty. If the keystore has not been initialized, the PIN for the softtoken is changeme, and you can use the pktool setpin command to reset the PIN. Note that a FIPS 140-2 approved key type and key length, RSA 2048, is specified in the command options.

$ pktool gencert keystore=pkcs11 label="My Cert" \
            subject="C=US, O=My Company, OU=Security Engineering Group, CN=MyCA" \
            serial=0x000000001 keytype=rsa keylen=2048
Enter pin for Sun Software PKCS#11 softtoken:Type PIN for token

$ pktool list
No.  Key Type  Key Len.  Key Label
----------------------------------------------------
Asymmetric public keys:
1    RSA                 My Cert
Certificates:
1    X.509 certificate
Label: My Cert
ID: d2:7e:20:04:a5:66:e6:31:90:d8:53:28:bc:ef:55:55:dc:a3:69:93
Subject: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA
Issuer: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA
...
...
Serial: 0x00000010
...

How to Import a Certificate Into Your Keystore

This procedure describes how to import a file with PKI information that is encoded with PEM or with raw DER into your keystore. For an export procedure, see How to Export a Certificate and Private Key in PKCS #12 Format.

Import the certificate.

$ pktool import keystore=keystore infile=infile-name label=label-name

If you are importing certificates and private keys in PKCS #12 format, provide passwords when prompted.
1. At the prompt, type the password for the file.
  If you are importing PKI information that is private, such as an export file in PKCS #12 format, the file requires a password. The creator of the file that you are importing provides you with the PKCS #12 password.
```
Enter password to use for accessing the PKCS12 file:Type PKCS #12 password
```
2. At the prompt, type the password for your keystore.
```
Enter pin for Sun Software PKCS#11 softtoken: Type PIN for token
```

Verify the contents of the keystore.

$ pktool list
Found number certificates.
1. (X.509 certificate)
Label:  label-name
ID: fingerprint that binds certificate to private key
Subject: subject-DN
Issuer:  distinguished-name
Serial:  hex-serial-number

2. ...

Example 4-2 Importing a PKCS #12 File Into Your Keystore

In the following example, the user imports a PKCS #12 file from a third party. The pktool import command extracts the private key and the certificate from the gracedata.p12 file and stores them in the user's preferred keystore.

$ pktool import keystore=pkcs11 infile=gracedata.p12 label=GraceCert
Enter password to use for accessing the PKCS12 file:Type PKCS #12 password
Enter pin for Sun Software PKCS#11 softtoken: Type PIN for token
Found 1 certificate(s) and 1 key(s) in gracedata.p12
$ pktool list
No.  Key Type  Key Len.  Key Label
----------------------------------------------------
Asymmetric public keys:
1    RSA                 GraceCert
Certificates:
1    X.509 certificate
Label: GraceCert
ID: 71:8f:11:f5:62:10:35:c2:5d:b4:31:38:96:04:80:25:2e:ad:71:b3
Subject: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA
Issuer: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA
Serial: 0x00000010

Example 4-3 Importing an X.509 Certificate Into Your Keystore

In the following example, the user imports an X.509 certificate in PEM format into the user's preferred keystore. This public certificate is not protected with a password. The user's public keystore is also not protected by a password.

$ pktool import keystore=pkcs11 infile=somecert.pem label="TheirCompany Root Cert"
$ pktool list
No.  Key Type  Key Len.  Key Label
Certificates:
1    X.509 certificate
Label: TheirCompany Root Cert
ID: ec:a2:58:af:83:b9:30:9d:de:b2:06:62:46:a7:34:49:f1:39:00:0e
Subject: C=US, O=TheirCompany, OU=Security, CN=TheirCompany Root CA
Issuer: C=US, O=TheirCompany, OU=Security, CN=TheirCompany Root CA
Serial: 0x00000001

How to Export a Certificate and Private Key in PKCS #12 Format

You can create a file in PKCS #12 format to export private keys and their associated X.509 certificate to other systems. Access to the file is protected by a password.

Find the certificate to export.

$ pktool list
Found number certificates.
1. (X.509 certificate)
Label:  label-name
ID: fingerprint that binds certificate to private key
Subject: subject-DN
Issuer:  distinguished-name
Serial:  hex-serial-number

2. ...

Export the keys and certificate.
Use the keystore and label from the pktool list command. Provide a file name for the export file. If the name contains a space, surround the name with double quotes.
```
$ pktool export keystore=keystore outfile=outfile-name label=label-name
               
```
Protect the export file with a password.
At the prompt, type the current password for the keystore. At this point, you create a password for the export file. The receiver must provide this password when importing the file.
```
Enter pin for Sun Software PKCS#11 softtoken: Type PIN for token
Enter password to use for accessing the PKCS12 file:Create PKCS #12 password
```
Tip:
Send the password separately from the export file. Best practice suggests that you provide the password out of band, such as during a telephone call.

Example 4-4 Exporting a Certificate and Private Key in PKCS #12 Format

In the following example, a user exports the private keys with their associated X.509 certificate into a standard PKCS #12 file. This file can be imported into other keystores. The PKCS #11 password protects the source keystore. The PKCS #12 password is used to protect private data in the PKCS #12 file. This password is required to import the file.

$ pktool list
No.  Key Type  Key Len.  Key Label
----------------------------------------------------
Asymmetric public keys:
1    RSA                 My Cert
Certificates:
1    X.509 certificate
Label: My Cert
ID: d2:7e:20:04:a5:66:e6:31:90:d8:53:28:bc:ef:55:55:dc:a3:69:93
Subject: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA
Issuer: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA
Serial: 0x000001

$ pktool export keystore=pkcs11 outfile=mydata.p12 label="My Cert"
Enter pin for Sun Software PKCS#11 softtoken: Type PIN for token
Enter password to use for accessing the PKCS12 file:Create PKCS #12 password

The user then telephones the recipient and provides the PKCS #12 password.

How to Create a PKCS #11 Keystore

Use this procedure to create a brand new PKCS #11 keystore. This same procedure also applies if you want to re-create a keystore that has been previously used. When creating keystores, you should use the pktool inittoken command as a preferred method instead of the traditional pktool setpin command.

Caution:

Using the pktool inittoken command in this procedure destroys all of the existing objects in the keystore. If you are re-creating a keystore that has been previously used, export the keystore's objects to a secure location. After you have completed the procedure, you can import the objects.

Export the objects in the current keystore.

See How to Export a Certificate and Private Key in PKCS #12 Format.
Create the keystore.
```
# pktool inittoken
               
```
If you create a brand new keystore without assigning it a name, then the default label Sun Software PKCS#11 softtoken is assigned to the keystore.

Depending on the conditions that apply, you can create the keystore in different ways. Refer to the pktool(1) man page and the following example to see how the pktool inittoken command can be used.
Import the objects to be used in the new keystore.

See How to Import a Certificate Into Your Keystore.
Display a list of tokens by using the pktool tokens command.

Note that the output of the pktool tokens command will include the metaslot only if the metaslot is enabled. Also, note that the metaslot is softtoken by default, but it can also be TPM, or other tokens if the user manually set up the metaslot. For further information, see Metaslot in Concepts in the Cryptographic Framework.

Example 4-5 Creating a Brand New Keystore With a New Name

This example shows how to assign a new name to the keystore that you are creating.

Note that you will be prompted to enter your Security Officer PIN to complete the process.

# pktool inittoken currlabel="Sun Software PKCS#11 softtoken" \
newlabel="Company XYZ softtoken"
Enter SO PIN: Type Security Officer PIN
Token Company XYZ softtoken initialized.
# pktool tokens
ID Slot Name                    Token Name            Flags 
-- ---------                    ----------            ----- 
1  Sun Crypto Softtoken         Company XYZ softtoken    LI 
Flags: L=Login required, I=Initialized, X=User PIN expired, 
S=SO PIN expired, R=Write protected

How to Generate a Passphrase by Using the pktool Command

You can generate a passphrase for an object in a keystore, and for the keystore itself. The passphrase is required to access the object or keystore. For an example of generating a passphrase for an object in a keystore, see Exporting a Certificate and Private Key in PKCS #12 Format.

Generate a passphrase for access to a keystore.
```
$ pktool setpin keystore=nss|pkcs11 [dir=directory]
```
The default directory for key storage is /var/ username.

The initial password for a PKCS #11 keystore is changeme. The initial password for an NSS keystore is an empty password.
Answer the prompts.
When prompted for the current token passphrase, type the token PIN for a PKCS #11 keystore, or press the Return key for an NSS keystore.
```
Enter current token passphrase:Type PIN or press the Return key
Create new passphrase:Type the passphrase that you want to use
Re-enter new passphrase:Retype the passphrase
Passphrase changed.
```
The keystore is now protected by passphrase. If you lose the passphrase, you lose access to the objects in the keystore.

Display a list of tokens.

$ pktool tokens

The output depends on whether the metaslot is enabled. Moreover, when the metaslot is enabled, or when there are more than two tokens present, the metaslot will also be presented as a virtual token in the list.

For more information about the metaslot, see Concepts in the Cryptographic Framework.

If the metaslot is enabled, the pktool token command generates output similar to the following:

ID Slot Name                     Token Name                  Flags
-- ---------                     ----------                  -----
0  Sun Metaslot                  Sun Metaslot                V
1  Sun Crypto Softtoken          softy                       LI
2  PKCS#11 Interface for TPM     TPM                         LIS
3  Oracle Key Management System  KMS                         LI

If the metaslot is disabled, the pktool token command generates output similar to the following:

ID Slot   Name                        Token Name                       Flags
--        ---------                   ----------                       -----
1         Sun Crypto Softtoken        Sun Software PKCS#11 softtoken   LIX
2         PKCS#11 Interface for TPM   TPM                              LXS

In the two output versions, flags can be any combination of the following:

L – login required
I – initialized
X – User PIN expired
S – SO PIN expired
R – Write protected
V – Virtual

Example 4-6 Protecting a Keystore With a Passphrase

The following example shows how to set the passphrase for an NSS database. Because no passphrase has been created, the user presses the Return key at the first prompt.

$ pktool setpin keystore=nss dir=/var/nss
Enter current token passphrase:Press the Return key
Create new passphrase: xxxx xxx xxx
Re-enter new passphrase: xxxx xxx xxx
Passphrase changed.

How to Generate a Key Pair by Using the pktool genkeypair Command

Some applications require a public/private key pair. In this procedure, you create these key pairs and store them.

If you plan to use a keystore, create the keystore.
- To create and initialize a PKCS #11 keystore, see How to Generate a Passphrase by Using the pktool setpin Command.
- To create and initialize an NSS keystore, see Protecting a Keystore With a Passphrase.
Create the key pair.

Use one of the following methods.
- Create the key pair and store the key pair in a file.
  
  File-based keys are created for applications that read keys directly from files on the disk. Typically, applications that directly use OpenSSL cryptographic libraries require that you store the keys and certificates for the application in files.
  
  Note:
  The file keystore does not support elliptic curve (ec) keys and certificates.
```
$ pktool genkeypair keystore=file outkey=key-filename \
[format=der|pem] [keytype=rsa|dsa] [keylen=key-size]
```
  keystore=file
  
  The value file specifies the file type of storage location for the key.
  
  outkey= key-filename
  
  Specifies the name of the file where the key pair is stored.
  
  format=der|pem
  
  Specifies the encoding format of the key pair. der output is binary, and pem output is ASCII.
  
  keytype=rsa|dsa
  
  Specifies the type of key pair that can be stored in a file keystore. For definitions, see DSA and RSA.
  
  keylen= key-size
  
  Specifies the length of the key in bits. The number must be divisible by 8. To determine possible key sizes, use the cryptoadm list -vm command.
- Create the key pair and store it in a PKCS #11 keystore.
  
  You must complete Step 1 before using this method.
  
  The PKCS #11 keystore is used to store objects on a hardware device. The device could be a trusted platform module (TPM) device or a smart card that is plugged into the Cryptographic Framework. PKCS #11 can also be used to store objects in the softtoken, or software-based token, which stores the objects in a private subdirectory on the disk. For more information, see the pkcs11_softtoken(7) man page.
  
  You can retrieve the key pair from the keystore by a label that you specify.
```
$ pktool genkeypair label=key-label \
[token=token[:manuf[:serial]]] \
[keytype=rsa|dsa|ec]  [curve=ECC-Curve-Name]]\
[keylen=key-size] [listcurves]
```
  label= key-label
  
  Specifies a label for the key pair. The key pair can be retrieved from the keystore by its label.
  
  token= token[:manuf[:serial]]
  
  Specifies the token name. By default, it is Sun Software PKCS#11 softtoken.
  
  keytype=rsa|dsa|ec [curve=ECC-Curve-Name]
  
  Specifies the keypair type. For the elliptic curve type, optionally specifies a curve name. Curve names are listed as output to the listcurves option.
  
  keylen= key-size
  
  Specifies the length of the key in bits. The number must be divisible by 8.
  
  listcurves
  
  Lists the elliptic curve names that can be used as values to the curve= option for an ec key type.
- Generate the key pair and store it in an NSS keystore.
  
  The NSS keystore is used by servers that rely on NSS as their primary cryptographic interface.
  
  You must complete Step 1 before using this method.
```
$ pktool keystore=nss genkeypair label=key-nickname \
[token=token[:manuf[:serial]]] \
[dir=directory-path] [prefix=database-prefix] \
[keytype=rsa|dsa|ec] [curve=ECC-Curve-Name]] \
[keylen=key-size] [listcurves]
```
  keystore=nss
  
  The value nss specifies the NSS type of storage location for the key.
  
  label= nickname
  
  Specifies a label for the key pair. The key pair can be retrieved from the keystore by its label.
  
  token= token[:manuf[:serial]]
  
  Specifies the token name. By default, it is Sun Software PKCS#11 softtoken.
  
  dir= directory
  
  Specifies the directory path to the NSS database. By default, directory is the current directory.
  
  prefix= database-prefix
  
  Specifies the prefix to the NSS database. The default is no prefix.
  
  keytype=rsa|dsa|ec [curve=ECC-Curve-Name]
  
  Specifies the keypair type. For the elliptic curve type, optionally specifies a curve name. Curve names are listed as output to the listcurves option.
  
  keylen= key-size
  
  Specifies the length of the key in bits. The number must be divisible by 8.
  
  listcurves
  
  Lists the elliptic curve names that can be used as values to the curve= option for an ec key type.

Verify that the key exists.

Use one of the following commands, depending on where you stored the key.

Verify the key in the key-filename file.

$ pktool list keystore=file objtype=key infile=key-filename
Found n keys.
Key #1 - keytype:location (keylen)

Verify the key in the PKCS #11 keystore.

$ pktool list objtype=key
Enter PIN for keystore:
Found n keys.
Key #1 - keytype:location (keylen)

Verify the key in the NSS keystore.

$ pktool list keystore=nss dir=directory objtype=key

Example 4-7 Creating a Key Pair by Using the pktool Command

In the following example, a user creates a PKCS #11 keystore for the first time. After determining the key sizes for RSA key pairs, the user then generates a key pair for an application. Finally, the user verifies that the key pair is in the keystore. The user notes that the second occurrence of the RSA key pair can be stored on hardware. Because the user does not specify a token argument, the key pair is stored as a Sun Software PKCS#11 softtoken.

# pktool setpin
Create new passphrase:
Re-enter new passphrase:xxxxxxxxxx
Passphrase changed.
$ cryptoadm list -vm | grep PAIR
...
CKM_DSA_KEY_PAIR_GEN       512  3072 .  .  .  .  .  .  .  .  .  X  .  .  .  .
CKM_RSA_PKCS_KEY_PAIR_GEN  256  8192 .  .  .  .  .  .  .  .  .  X  .  .  .  .
...
CKM_RSA_PKCS_KEY_PAIR_GEN  256  2048 X  .  .  .  .  .  .  .  .  X  .  .  .  .
ecc: CKM_EC_KEY_PAIR_GEN,CKM_ECDH1_DERIVE,CKM_ECDSA,CKM_ECDSA_SHA1
$ pktool genkeypair label=specialappkeypair keytype=rsa keylen=2048
Enter PIN for Sun Software PKCS#11 softtoken  : xxxxxxxxxx

$ pktool list
Enter PIN for Sun Software PKCS#11 softtoken  : xxxxxxxxxx
No.      Key Type      Key Len.      Key Label
----------------------------------------------------
Asymmetric public keys:
1        RSA                         specialappkeypair

Example 4-8 Creating a Key Pair That Uses the Elliptic Curve Algorithm

In the following example, a user adds an elliptic curve (ec) key pair to the keystore, specifies a curve name, and verifies that the key pair is in the keystore.

$ pktool genkeypair listcurves
secp112r1, secp112r2, secp128r1, secp128r2, secp160k1
.
.
.
c2pnb304w1, c2tnb359v1, c2pnb368w1, c2tnb431r1, prime192v2
prime192v3
$ pktool genkeypair label=eckeypair keytype=ec curves=c2tnb431r1
$ pktool list
Enter PIN for Sun Software PKCS#11 softtoken  : xxxxxxxxxx
No.  Key Type  Key Len.  Key Label
----------------------------------------------------
Asymmetric public keys:
1    ECDSA               eckeypair

How to Sign a Certificate Request by Using the pktool signcsr Command

This procedure assumes that you are a certificate authority (CA), you have received a CSR, and it is stored in a file. For an example of creating a CSR, see Example 4-9.

This procedure is used to sign a PKCS #10 certificate signing request (CSR). The CSR can be in PEM or DER format. The signing process issues an X.509 v3 certificate. To generate a PKCS #10 CSR, see the pktool(1) man page.

Collect the following information for the required arguments to the pktool signcsr command:

signkey

If you have stored the signer's key in a PKCS #11 keystore, signkey is the label that retrieves this private key.

If you have stored the signer's key in an NSS keystore or a file keystore, signkey is the file name that holds this private key.

csr

Specifies the file name of the CSR.

serial

Specifies the serial number of the signed certificate.

outcert

Specifies the file name for the signed certificate.

issuer

Specifies your CA issuer name in distinguished name (DN) format.

For information about optional arguments to the signcsr subcommand, see the pktool(1) man page.

Sign the request and issue the certificate.

For example, the following command signs the certificate with the signer's key from the PKCS #11 repository:

# pktool signcsr signkey=CASigningKey \
                  csr=fromExampleCoCSR \
                  serial=0x12345678 \
                  outcert=ExampleCoCert2010 \
                  issuer="O=Oracle Corporation, \
OU=Oracle Solaris Security Technology, L=Redwood City, ST=CA, C=US, \
CN=rootsign Oracle"

The following command signs the certificate with the signer's key from a file:

# pktool signcsr signkey=CASigningKey \
                  csr=fromExampleCoCSR \
                  serial=0x12345678 \
                  outcert=ExampleCoCert2010 \
                  issuer="O=Oracle Corporation, \
OU=Oracle Solaris Security Technology, L=Redwood City, ST=CA, C=US, \
CN=rootsign Oracle"

Send the certificate to the requester.

You can use email, a web site, or another mechanism to deliver the certificate to the requester.

For example, you could use email to send the ExampleCoCert2010 file to the requester.

Example 4-9 Generating a CSR

This example shows two methods to generate a CSR.

Use the pktool command and store the CSR in the PKCS #11 keystore. You must provide the password to the keystore.

$ pktool gencsr keystore=pkcs11 label=example3csr \
   keytype=rsa keylen=2048 hash=sha2 \
   format=pem outcsr=/var/tmp/example3.csr-1 \
   subject="CN=example3.company.au, OU=HR Department, O=Example3, L=Sydney, ST=NSW, C=AU"

Use the openssl command to generate the CSR.

$ openssl req -text -noout -in /var/tmp/example3.csr-1

How to Manage Third-Party Plugins in KMF

You identify your plugin by giving it a keystore name. When you add the plugin to KMF, the software identifies it by its keystore name. The plugin can be defined to accept an option. This procedure includes how to remove the plugin from KMF.

Install the plugin.
```
$ /usr/bin/kmfcfg install keystore=keystore-name \
modulepath=path-to-plugin [option="option-string"]
```
where:

keystore-name

Specifies a unique name for the keystore that you provide.

path-to-plugin

Specifies the full path to the shared library object for the KMF plugin.

option-string

Specifies an optional argument to the shared library object.

List the plugins.

$ kmfcfg list plugin
keystore-name:path-to-plugin [(built-in)] | [;option=option-string]

To remove the plugin, uninstall it and verify its removal.

$ kmfcfg uninstall keystore=keystore-name
$ kmfcfg plugin list

Example 4-10 Calling a KMF Plugin With an Option

In the following example, the administrator stores a KMF plugin in a site-specific directory. The plugin is defined to accept a debug option. The administrator adds the plugin and verifies that the plugin is installed.

# /usr/bin/kmfcfg install keystore=mykmfplug \
modulepath=/lib/security/site-modules/mykmfplug.so
$ kmfcfg list plugin
KMF plugin information:
-----------------------
pkcs11:kmf_pkcs11.so.1 (built-in)
file:kmf_openssl.so.1 (built-in)
nss:kmf_nss.so.1 (built-in)
mykmfplug:/lib/security/site-modules/mykmfplug.so
# kmfcfg modify plugin keystore=mykmfplug option="debug"
# kmfcfg list plugin
KMF plugin information:
-----------------------
...
mykmfplug:/lib/security/site-modules/mykmfplug.so;option=debug

The plugin now runs in debugging mode.

Managing Certificates in the Oracle Solaris CA Keystore

Oracle Solaris provides a keystore for Certificate Authority (CA) certificate files. To manage the keystore, you restart the SMF ca-certificates service after you add, remove, or exclude certificates from the keystore.

X.509 certificates contain an RSA public key and the key's signer ("CN" or "Subject"). The key and signer verifies that some file or object was signed with the key holder's private key. CA certificates are issued by well-known organizations to verify that a certificate is legitimate and that the public key in the certificate can be trusted.

Oracle Solaris keeps the CA certificates in the /etc/certs/CA directory. Hashed links to the CA certificates are in the /etc/openssl/certs directory to enable fast lookup and access, typically by OpenSSL. Usually, each filename in the /etc/certs/CA directory is the certificate holder's CN with spaces replaced by underscores ("_") and appended with a .pem extension. For example, the file /etc/certs/CA/ExampleCo-_G3.pem contains the certificate for CN "ExampleCo Class 4 Public Primary Certification Authority - G3".

Note:

Certificates in the /etc/certs directory are not automatically included in the Java keystore. You must add them separately.

You can add certificates and exclude certificates.

How to Add a Certificate to the Oracle Solaris CA Keystore

You must assume the root role. For more information, see Using Your Assigned Administrative Rights in Securing Users and Processes in Oracle Solaris 11.4.

Verify that the CA certificate is legitimate.

Check with the issuer of the CA certificate directly.

Caution:
Do not rely on verification from an entity that did not issue the CA certificate. Do not install invalid CA certificates on your system that your software would treat as trustworthy.
Strip extra text from the certificate.

Remove any text that surrounds the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" lines. Some applications are not able to handle the extra text.
Verify that the certificate is not corrupt.
For example, display the text of a certificate by using the openssl command.
```
# openssl x509 -noout -text -in Example_Root_CA.pem
```
The output should display the issuer, owner (Subject/DN), validity dates, signature algorithm, and public key, among other information.

Verify that the certificate file is world-readable.

If it is not, use the chmod command to make the file world-readable.

# chmod a+r Example_Root_CA.pem; ls -l Example_Root_CA.pem
-rw-r--r--   1 root   sys    1500 Sep  10 10:10 Example_Root_CA.pem

Copy the certificate to the /etc/certs/CA directory.
For example:
```
# cp -p Example_Root_CA.pem /etc/certs/CA/
```
Restart the ca-certificates service.
```
# /usr/sbin/svcadm restart /system/ca-certificates
```
The service adds the certificate to the /etc/certs/ca-certificates.crt file and adds a hashed link in the /etc/openssl/certs directory.

Verify that the CA certificate service has restarted.

When the service restarts, it processes your new CA certificate.

$ svcs -x ca-certificates
svc:/system/ca-certificates:default (CA Certificates Service)
 State: online since 10:10:10 2017
   See: openssl(5)
   See: /var/svc/log/system-ca-certificates:default.log
Impact: None.

If the service hasn't started, the certificate could be corrupt or could be a duplicate of an existing CA certificate. Look for error messages in the log file listed in the svcs -x command output. Also check the /system/volatile/system-ca-certificates:default.log file.

How to Exclude Certificates From the Oracle Solaris CA Keystore

You must assume the root role. For more information, see Using Your Assigned Administrative Rights in Securing Users and Processes in Oracle Solaris 11.4.

Excluding prevents Oracle Solaris libraries and programs from using the excluded CA certificate. Excluded certificates are not copied to the /etc/certs/ca-certificates.crt and are not linked to from the OpenSSL CA certificate directory, /etc/openssl/certs.

Collect the names of excluded certificates.

Add the certificates to the ca-certificates SMF service.

In this example, the administrator adds three excluded certificates and verifies that they are in the exclusion list.

# svccfg -s ca-certificates
svc:/system/ca-certificates> addpropvalue config/exclude/example astring: Example_Root_CA1.pem
svc:/system/ca-certificates> addpropvalue config/exclude/example astring: Example_root_CA_temp1.pem
svc:/system/ca-certificates> addpropvalue config/exclude/example astring: Example_root_CA_temp2.pem
svc:/system/ca-certificates> listprop config/exclude
config/exclude            application
config/exclude/example    astring   'Example_Root_CA1.pem' 'Example_root_CA_temp1.pem' 'Example_root_CA_temp2.pem'
svc:/system/ca-certificates> exit

Restart the ca-certificates service.

# /usr/sbin/svcadm restart /system/ca-certificates

Verify that the CA certificate service has restarted.

When the service restarts, it removes the excluded certificates from the /etc/certs/ca-certificates.crt file and the /etc/openssl/certs directory.

$ svcs -x ca-certificates
svc:/system/ca-certificates:default (CA Certificates Service)
 State: online since 10:10:10 2017
   See: openssl(5)
   See: /var/svc/log/system-ca-certificates:default.log
Impact: None.