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.
|
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.
$ pktool gencert [keystore=keystore] label=label-name \ subject=subject-DN serial=hex-serial-number keytype=rsa/dsa keylen=key-size
Specifies the keystore by type of public key object. The value can be nss, pkcs11, or file. This keyword is optional.
Specifies a unique name that the issuer gives to the certificate.
Specifies the distinguished name for the certificate.
Specifies the serial number in hexadecimal format. The issuer of the certificate chooses the number, such as 0x0102030405.
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.3.
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.3.
$ 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.
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 ...
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 Example 28, Exporting a Certificate and Private Key in PKCS #12 Format.
$ pktool import keystore=keystore infile=infile-name label=label-name
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
Enter pin for Sun Software PKCS#11 softtoken: Type PIN for token
$ 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. ...
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: 0x00000010Example 27 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
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.
$ 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. ...
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
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
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.
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 Example 28, Exporting a Certificate and Private Key in PKCS #12 Format.
$ 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.
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.
# pktool tokens
The output depends on whether the metaslot is enabled. 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 1 Sun Crypto Softtoken Sun Software PKCS#11 softtoken LIX 2 PKCS#11 Interface for TPM TPM LXS
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
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: has8n0NdaH
Re-enter new passphrase: has8n0NdaH
Passphrase changed.
Some applications require a public/private key pair. In this procedure, you create these key pairs and store them.
Use one of the following methods.
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.
$ pktool genkeypair keystore=file outkey=key-filename \ [format=der|pem] [keytype=rsa|dsa] [keylen=key-size]
The value file specifies the file type of storage location for the key.
Specifies the name of the file where the key pair is stored.
Specifies the encoding format of the key pair. der output is binary, and pem output is ASCII.
Specifies the type of key pair that can be stored in a file keystore. For definitions, see DSA and RSA.
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.
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 Sun Crypto Accelerator 6000 card, 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(5) 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]
Specifies a label for the key pair. The key pair can be retrieved from the keystore by its label.
Specifies the token name. By default, it is Sun Software PKCS#11 softtoken.
Specifies the keypair type. For the elliptic curve type, optionally specifies a curve name. Curve names are listed as output to the listcurves option.
Specifies the length of the key in bits. The number must be divisible by 8.
Lists the elliptic curve names that can be used as values to the curve= option for an ec key type.
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]
The value nss specifies the NSS type of storage location for the key.
Specifies a label for the key pair. The key pair can be retrieved from the keystore by its label.
Specifies the token name. By default, it is Sun Software PKCS#11 softtoken.
Specifies the directory path to the NSS database. By default, directory is the current directory.
Specifies the prefix to the NSS database. The default is no prefix.
Specifies the keypair type. For the elliptic curve type, optionally specifies a curve name. Curve names are listed as output to the listcurves option.
Specifies the length of the key in bits. The number must be divisible by 8.
Lists the elliptic curve names that can be used as values to the curve= option for an ec key type.
Use one of the following commands, depending on where you stored the key.
$ pktool list keystore=file objtype=key infile=key-filename Found n keys. Key #1 - keytype:location (keylen)
$ pktool list objtype=key Enter PIN for keystore: Found n keys. Key #1 - keytype:location (keylen)
$ pktool list keystore=nss dir=directory objtype=key
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:Retype password 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 :Type password $ pktool list Enter PIN for Sun Software PKCS#11 softtoken :Type password No. Key Type Key Len. Key Label ---------------------------------------------------- Asymmetric public keys: 1 RSA specialappkeypairExample 31 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 :Type password
No. Key Type Key Len. Key Label
----------------------------------------------------
Asymmetric public keys:
1 ECDSA eckeypair
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.
Before You Begin
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 32, Generating a CSR.
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.
Specifies the file name of the CSR.
Specifies the serial number of the signed certificate.
Specifies the file name for the signed certificate.
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.
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"
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.
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
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.
$ /usr/bin/kmfcfg install keystore=keystore-name \ modulepath=path-to-plugin [option="option-string"]
where:
Specifies a unique name for the keystore that you provide.
Specifies the full path to the shared library object for the KMF plugin.
Specifies an optional argument to the shared library object.
$ kmfcfg list plugin keystore-name:path-to-plugin [(built-in)] | [;option=option-string]
$ kmfcfg uninstall keystore=keystore-name $ kmfcfg plugin list
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.