Go to main content

Managing Encryption and Certificates in Oracle® Solaris 11.4

Exit Print View

Updated: February 2019
 
 

How to Generate a Symmetric Key by Using the pktool Command

Some applications require a symmetric key for encryption and decryption of communications. In this procedure, you create a symmetric key and store it.

If your site has a random number generator, you can use the generator to create a random number for the key. This procedure does not use your site's random number generator.

  1. (Optional) If you plan to use a keystore, create it.

    To create and initialize a PKCS #11 keystore, see How to Generate a Passphrase by Using the pktool setpin Command.

  2. Generate a random number for use as a symmetric key.

    For FIPS 140-2 approved algorithms, select a key length that has been validated for FIPS 140-2. See FIPS 140-2 Algorithms in the Cryptographic Framework in Using a FIPS 140-2 Enabled System in Oracle Solaris 11.4.

    Use one of the following methods.

    • Generate a key and store it in a file.

      The advantage of a file-stored key is that you can extract the key from this file to use in an application's key file, such as the /etc/inet/secret/ipseckeys file or IPsec. The usage statement shows the arguments.

      $ pktool genkey keystore=file
      ...genkey keystore=file
      outkey=key-fn
      [ keytype=aes|arcfour|des|3des|generic ]
      [ keylen=key-size (AES, ARCFOUR or GENERIC only)]
      [ print=y|n ]
      outkey=key-fn

      The filename where the key is stored.

      keytype=specific-symmetric-algorithm

      For a symmetric key of any length, the value is generic. For a particular algorithm, specify aes, arcfour, des, or 3des.

      keylen=size-in-bits

      The length of the key in bits. The number must be divisible by 8. Do not specify for des or 3des.

      print=y

      Prints the key to the terminal window. By default, the value of print is n.

    • Generate a key and store it in a PKCS #11 keystore.

      The advantage of the PKCS #11 keystore is that you can retrieve the key by its label. This method is useful for keys that encrypt and decrypt files. You must complete Step 1 before using this method. The usage statement shows the arguments. The brackets around the keystore argument indicate that when the keystore argument is not specified, the key is stored in the PKCS #11 keystore.

      $ pktool genkey keystore=pkcs11
      ...genkey [ keystore=pkcs11 ]
      label=key-label
      [ keytype=aes|arcfour|des|3des|generic ]
      [ keylen=key-size (AES, ARCFOUR or GENERIC only)]
      [ token=token[:manuf[:serial]]]
      [ sensitive=y|n ]
      [ extractable=y|n ]
      [ print=y|n ]
      label=key-label

      A user-specified label for the key. The key can be retrieved from the keystore by its label.

      keytype=specific-symmetric-algorithm

      For a symmetric key of any length, the value is generic. For a particular algorithm, specify aes, arcfour, des, or 3des.

      keylen=size-in-bits

      The length of the key in bits. The number must be divisible by 8. Do not specify for des or 3des.

      token=token

      The token name. By default, it is Sun Software PKCS#11 softtoken.

      sensitive=n

      Specifies the sensitivity of the key. When the value is y, the key cannot be printed by using the print=y argument. By default, the value of sensitive is n.

      extractable=y

      Specifies that the key can be extracted from the keystore. Specify n to prevent the key from being extracted.

      print=y

      Prints the key to the terminal window. By default, the value of print is n.

  3. (Optional) Verify that the key exists.

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

    • Verify the key in the key-fn file.
      $ pktool list keystore=file objtype=key [infile=key-fn]
      Found n keys.
      Key #1 - keytype:location (keylen)
    • Verify the key in the PKCS #11 keystore.
      For PKCS #11, use the following command:
      $ pktool list keystore=pkcs11 objtype=key
      Enter PIN for keystore:
      Found n keys.
      Key #1 - keytype:location (keylen)
Example 3  Creating a Symmetric Key by Using the pktool Command

In the following example, a user creates a PKCS #11 keystore for the first time and then generates a large symmetric key for an application. Finally, the user verifies that the key is in the keystore.

Note that the initial password for a PKCS #11 keystore is changeme.

$ pktool setpin
Create new passphrase:xxxxxxxx
Re-enter new passphrase:xxxxxxxx
Passphrase changed.
$ pktool genkey label=specialappkey keytype=generic keylen=1024
Enter PIN for Sun Software PKCS#11 softtoken  :xxxxxxxx

$ pktool list objtype=key
Enter PIN for Sun Software PKCS#11 softtoken  :Type password
No.      Key Type      Key Len.      Key Label
----------------------------------------------------
Symmetric keys:
1        Symmetric     1024          specialappkey
Example 4  Creating a FIPS 140-2 Approved AES Key by Using the pktool Command

In the following example, a secret key for the AES algorithm is created using a FIPS 140-2 approved algorithm and key length. The key is stored in a local file for later decryption. The command protects the file with 400 permissions. When the key is created, the print=y option displays the generated key in the terminal window.

The user who owns the keyfile retrieves the key by using the od command.

$ pktool genkey keystore=file outkey=256bit.file1 keytype=aes keylen=256 print=y
Key Value ="aaa2df1d10f02eaee2595d48964847757a6a49cf86c4339cd5205c24ac8c8873"
$ od -x 256bit.file1

0000000 aaa2 df1d 10f0 2eae e259 5d48 9648 4775
0000020 7a6a 49cf 86c4 339c d520 5c24 ac8c 8873
0000040
Example 5  Creating a Symmetric Key for IPsec Security Associations

In the following example, the administrator manually creates the keying material for IPsec SAs and stores them in files. Then, the administrator copies the keys to the /etc/inet/secret/ipseckeys file, destroys the original files, and sends the ipseckeys file to the communicating system by a secure mechanism.

First, the administrator creates and displays the keys that the IPsec policy requires:

$ pktool genkey keystore=file outkey=ipencrin1 keytype=aes keylen=256 print=y
Key Value ="294979e512cb8e79370dabeca...................dc3fcbb849e78d2d6bd2049"
$ pktool genkey keystore=file outkey=ipencrout1 keytype=aes keylen=256 print=y
Key Value ="9678f80e33406c86e3d1686e5...................0406bd0434819c20d09d204"
$ pktool genkey keystore=file outkey=ipspi1 keytype=aes keylen=32 print=y
Key Value ="acb...0"
$ pktool genkey keystore=file outkey=ipspi2 keytype=aes keylen=32 print=y
Key Value ="191...5"
$ pktool genkey keystore=file outkey=ipsha21 keytype=aes keylen=256 print=y
Key Value ="659c20f2d6c3f9570bcee93e9...................3369f72c5c786af4177fe9e"
$ pktool genkey keystore=file outkey=ipsha22 keytype=aes keylen=256 print=y
Key Value ="b041975a0e1fce0503665c396....................cf87b0a837b2da5d82c810"

Then, the administrator creates the following /etc/inet/secret/ipseckeys file:

##   SPI values require a leading 0x.
##   Backslashes indicate command continuation.
##
## for outbound packets on this system
add esp spi 0xacb...20 \
src 192.0.2.1 dst 192.0.2.2 \
encr_alg aes auth_alg sha256  \
encrkey  294979e512cb8e79370dabeca...................dc3fcbb849e78d2d6bd2049 \
authkey  659c20f2d6c3f9570bcee93e9...................3369f72c5c786af4177fe9e
##
## for inbound packets
add esp spi 0x191...5 \
src 192.0.2.2 dst 192.0.2.1 \
encr_alg aes auth_alg sha256  \
encrkey 9678f80e33406c86e3d1686e5...................0406bd0434819c20d09d204 \
authkey b041975a0e1fce0503665c396....................cf87b0a837b2da5d82c810

After verifying that the syntax of the ipseckeys file is valid, the administrator destroys the original key files.

$ ipseckey -c /etc/inet/secret/ipseckeys
$ rm ipencrin1 ipencrout1 ipspi1 ipspi2 ipsha21 ipsha22

The administrator copies the ipseckeys file to the communicating system by using the ssh command or another secure mechanism. On the communicating system, the protections are reversed. The first entry in the ipseckeys file protects inbound packets, and the second entry protects outbound packets. No keys are generated on the communicating system.

Next Steps

To proceed with using the key to create a message authentication code (MAC) for a file, see How to Compute a MAC of a File.