Part IV Solaris Cryptographic Services

This section describes the centralized cryptographic and public key technology services that the Solaris OS provides.

Chapter 13 Solaris Cryptographic Framework (Overview)

This chapter describes the Solaris Cryptographic Framework. The following is a list of the information in this chapter.

• What's New in the Solaris Cryptographic Framework?

• Solaris Cryptographic Framework

• Terminology in the Solaris Cryptographic Framework

• Scope of the Solaris Cryptographic Framework

• Administrative Commands in the Solaris Cryptographic Framework

• User-Level Commands in the Solaris Cryptographic Framework

• Plugins to the Solaris Cryptographic Framework

• Cryptographic Services and Zones

To administer and use the Solaris Cryptographic Framework, see Chapter 14, Solaris Cryptographic Framework (Tasks).

What's New in the Solaris Cryptographic Framework?

Solaris 10 1/06: The framework library, libpkcs11.so, contains a new component, the metaslot. The metaslot serves as a single virtual slot with the combined capabilities of all tokens and slots that have been installed in the framework. Effectively, the metaslot enables an application to transparently connect with any available cryptographic service through a single slot.

• For more information, see the definitions of slot, metaslot, and token in Terminology in the Solaris Cryptographic Framework.

• To administer the metaslot, see the cryptoadm(1M) man page.

• For a complete listing of new Solaris features and a description of Solaris releases, see Solaris 10 What’s New.

Solaris Cryptographic Framework

The Solaris Cryptographic Framework provides a common store of algorithms and PKCS #11 libraries to handle cryptographic requirements. The PKCS #11 libraries are implemented according to the following standard: RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki).

At the kernel level, the framework currently handles cryptographic requirements for Kerberos and IPsec. User-level consumers include libsasl and IKE.

Export law in the United States requires that the use of open cryptographic interfaces be restricted. The Solaris Cryptographic Framework satisfies the current law by requiring that kernel cryptographic providers and PKCS #11 cryptographic providers be signed. For further discussion, see Binary Signatures for Third-Party Software.

The framework enables providers of cryptographic services to have their services used by many consumers in the Solaris Operating System. Another name for providers is plugins. The framework allows three types of plugins:

• User-level plugins – Shared objects that provide services by using PKCS #11 libraries, such as pkcs11_softtoken.so.1.

• Kernel-level plugins – Kernel modules that provide implementations of cryptographic algorithms in software, such as AES.

  Many of the algorithms in the framework are optimized for x86 with the SSE2 instruction set and for SPARC hardware.

• Hardware plugins – Device drivers and their associated hardware accelerators. The Niagara chips, the ncp and n2cp device drivers, are one example. A hardware accelerator offloads expensive cryptographic functions from the operating system. The Sun Crypto Accelerator 6000 board is one example.

The framework implements a standard interface, the PKCS #11, v2.11 library, for user-level providers. The library can be used by third-party applications to reach providers. Third parties can also add signed libraries, signed kernel algorithm modules, and signed device drivers to the framework. These plugins are added when the pkgadd utility installs the third-party software. For a diagram of the major components of the framework, see Chapter 8, Introduction to the Oracle Solaris Cryptographic Framework, in Oracle Solaris Security for Developers Guide.

Terminology in the Solaris Cryptographic Framework

The following list of definitions and examples is useful when working with the cryptographic framework.

• Algorithms – Cryptographic algorithms. These are established, recursive computational procedures that encrypt or hash input. Encryption algorithms can be symmetric or asymmetric. Symmetric algorithms use the same key for encryption and decryption. Asymmetric algorithms, which are used in public-key cryptography, require two keys. Hashing functions are also algorithms.

  Examples of algorithms include:

  • Symmetric algorithms, such as AES and ARCFOUR

  • Asymmetric algorithms, such as Diffie-Hellman and RSA

  • Hashing functions, such as MD5

• Consumers – Are users of the cryptographic services that come from providers. Consumers can be applications, end users, or kernel operations.

  Examples of consumers include:

  • Applications, such as IKE

  • End users, such as an ordinary user who runs the encrypt command

  • Kernel operations, such as IPsec

• Mechanism – Is the application of a mode of an algorithm for a particular purpose.

  For example, a DES mechanism that is applied to authentication, such as CKM_DES_MAC, is a separate mechanism from a DES mechanism that is applied to encryption, CKM_DES_CBC_PAD.

• Metaslot – Is a single slot that presents a union of the capabilities of other slots which are loaded in the framework. The metaslot eases the work of dealing with all of the capabilities of the providers that are available through the framework. When an application that uses the metaslot requests an operation, the metaslot figures out which actual slot should perform the operation. Metaslot capabilities are configurable, but configuration is not required. The metaslot is on by default. To configure the metaslot, see the cryptoadm(1M) man page.

• Mode – Is a version of a cryptographic algorithm. For example, CBC (Cipher Block Chaining) is a different mode from ECB (Electronic Code Book). The AES algorithm has two modes, CKM_AES_ECB and CKM_AES_CBC.

• Policy – Is the choice, by an administrator, of which mechanisms to make available for use. By default, all providers and all mechanisms are available for use. The disabling of any mechanism would be an application of policy. The enabling of a disabled mechanism would also be an application of policy.

• Providers – Are cryptographic services that consumers use. Providers plug in to the framework, so are also called plugins.

  Examples of providers include:

  • PKCS #11 libraries, such as pkcs11_softtoken.so

  • Modules of cryptographic algorithms, such as aes and arcfour

  • Device drivers and their associated hardware accelerators, such as the mca driver for the Sun Crypto 6000 accelerator

• Slot – Is an interface to one or more cryptographic devices. Each slot, which corresponds to a physical reader or other device interface, might contain a token. A token provides a logical view of a cryptographic device in the framework.

• Token – In a slot, a token provides a logical view of a cryptographic device in the framework.

Scope of the Solaris Cryptographic Framework

The framework provides commands for administrators, for users, and for developers who supply providers:

• Administrative commands – The cryptoadm command provides a list subcommand to list the available providers and their capabilities. Ordinary users can run the cryptoadm list and the cryptoadm --help commands.

  All other cryptoadm subcommands require you to assume a role that includes the Crypto Management rights profile, or to become superuser. Subcommands such as disable, install, and uninstall are available for administering the framework. For more information, see the cryptoadm(1M) man page.

  The svcadm command is used to manage the kcfd daemon, and to refresh cryptographic policy in the kernel. For more information, see the svcadm(1M) man page.

• User-level commands – The digest and mac commands provide file integrity services. The encrypt and decrypt commands protect files from eavesdropping. To use these commands, see Protecting Files With the Solaris Cryptographic Framework (Task Map).

• Binary signatures for third-party providers – The elfsign command enables third parties to sign binaries for use within the framework. Binaries that can be added to the framework are PKCS #11 libraries, kernel algorithm modules, and hardware device drivers. To use the elfsign command, see Appendix F, Packaging and Signing Cryptographic Providers, in Oracle Solaris Security for Developers Guide.

Administrative Commands in the Solaris Cryptographic Framework

The cryptoadm command administers a running cryptographic framework. The command is part of the Crypto Management rights profile. This profile can be assigned to a role for secure administration of the cryptographic framework. The cryptoadm command manages the following:

• Displaying cryptographic provider information

• Disabling or enabling provider mechanisms

• Solaris 10 1/06: Disabling or enabling the metaslot

The svcadm command is used to enable, refresh, and disable the cryptographic services daemon, kcfd. This command is part of the Solaris service management facility, smf. svc:/system/cryptosvcs is the service instance for the cryptographic framework. For more information, see the smf(5) and svcadm(1M) man pages.

User-Level Commands in the Solaris Cryptographic Framework

The Solaris Cryptographic Framework provides user-level commands to check the integrity of files, to encrypt files, and to decrypt files. A separate command, elfsign, enables providers to sign binaries for use with the framework.

• digest command – Computes a message digest for one or more files or for stdin. A digest is useful for verifying the integrity of a file. SHA1 and MD5 are examples of digest functions.

• mac command – Computes a message authentication code (MAC) for one or more files or for stdin. A MAC associates data with an authenticated message. A MAC enables a receiver to verify that the message came from the sender and that the message has not been tampered with. The sha1_mac and md5_hmac mechanisms can compute a MAC.

• encrypt command – Encrypts files or stdin with a symmetric cipher. The encrypt -l command lists the algorithms that are available. Mechanisms that are listed under a user-level library are available to the encrypt command. The framework provides AES, DES, 3DES (Triple-DES), and ARCFOUR mechanisms for user encryption.

• decrypt command – Decrypts files or stdin that were encrypted with the encrypt command. The decrypt command uses the identical key and mechanism that were used to encrypt the original file.

Binary Signatures for Third-Party Software

The elfsign command provides a means to sign providers to be used with the Solaris Cryptographic Framework. Typically, this command is run by the developer of a provider.

The elfsign command has subcommands to request a certificate from Sun and to sign binaries. Another subcommand verifies the signature. Unsigned binaries cannot be used by the Solaris Cryptographic Framework. To sign one or more providers requires the certificate from Sun and the private key that was used to request the certificate. For more information, see Appendix F, Packaging and Signing Cryptographic Providers, in Oracle Solaris Security for Developers Guide.

Plugins to the Solaris Cryptographic Framework

Third parties can plug their providers into the Solaris Cryptographic Framework. A third-party provider can be one of the following objects:

• PKCS #11 shared library

• Loadable kernel software module, such as an encryption algorithm, MAC function, or digest function

• Kernel device driver for a hardware accelerator

The objects from a provider must be signed with a certificate from Sun. The certificate request is based on a private key that the third party selects, and a certificate that Sun provides. The certificate request is sent to Sun, which registers the third party and then issues the certificate. The third party then signs its provider object with the certificate from Sun.

The loadable kernel software modules and the kernel device drivers for hardware accelerators must also register with the kernel. Registration is through the Solaris Cryptographic Framework SPI (service provider interface).

To install the provider, the third party provides a package that installs the signed object and the certificate from Sun. The package must include the certificate, and enable the administrator to place the certificate in a secure directory. For more information, see the Appendix F, Packaging and Signing Cryptographic Providers, in Oracle Solaris Security for Developers Guide.

Cryptographic Services and Zones

The global zone and each non-global zone has its own /system/cryptosvc service. When the cryptographic service is enabled or refreshed in the global zone, the kcfd daemon starts in the global zone, user-level policy for the global zone is set, and kernel policy for the system is set. When the service is enabled or refreshed in a non-global zone, the kcfd daemon starts in the zone, and user-level policy for the zone is set. Kernel policy was set by the global zone.

For more information on zones, see Part II, Zones, in System Administration Guide: Oracle Solaris Containers-Resource Management and Oracle Solaris Zones. For more information on the service management facility that manages persistent applications, see Chapter 18, Managing Services (Overview), in System Administration Guide: Basic Administration and the smf(5) man page.

Chapter 14 Solaris Cryptographic Framework (Tasks)

This chapter describes how to use the Solaris Cryptographic Framework. The following is a list of information in this chapter.

• Using the Cryptographic Framework (Task Map)

• Protecting Files With the Solaris Cryptographic Framework (Task Map)

• Administering the Cryptographic Framework (Task Map)

Using the Cryptographic Framework (Task Map)

The following task map points to tasks for using the cryptographic framework.

Protecting Files With the Solaris Cryptographic Framework (Task Map)

The Solaris Cryptographic Framework can help you protect your files. The following task map points to procedures for listing the available algorithms, and for protecting your files cryptographically.

Protecting Files With the Solaris Cryptographic Framework

This section describes how to generate symmetric keys, how to create checksums for file integrity, and how to protect files from eavesdropping. The commands in this section can be run by regular users. Developers can write scripts that use these commands.

How to Generate a Symmetric Key by Using the dd Command

A key is needed to encrypt files and to generate the MAC of a file. The key should be derived from a random pool of numbers.

If your site has a random number generator, use the generator. Otherwise, you can use the dd command with the Solaris /dev/urandom device as input. For more information, see the dd(1M) man page.

1. Determine the key length that your algorithm requires.

   1. List the available algorithms.

      % encrypt -l Algorithm Keysize: Min Max (bits) ------------------------------------------ aes 128 128 arcfour 8 128 des 64 64 3des 192 192 % mac -l Algorithm Keysize: Min Max (bits) ------------------------------------------ des_mac 64 64 sha1_hmac 8 512 md5_hmac 8 512 sha256_hmac 8 512 sha384_hmac 8 1024 sha512_hmac 8 1024

   2. Determine the key length in bytes to pass to the dd command.

      Divide the minimum and maximum key sizes by 8. When the minimum and maximum key sizes are different, intermediate key sizes are possible. For example, the value 8, 16, or 64 can be passed to the dd command for the sha1_hmac and md5_hmac functions.

2. Generate the symmetric key.

   % dd if=/dev/urandom of=keyfile bs=n count=n

   if=file

   Is the input file. For a random key, use the /dev/urandom file.

   of=keyfile

   Is the output file that holds the generated key.

   bs=n

   Is the key size in bytes. For the length in bytes, divide the key length in bits by 8.

   count=n

   Is the count of the input blocks. The number for n should be 1.

3. Store your key in a protected directory.

   The key file should not be readable by anyone but the user.

   % chmod 400 keyfile

Example 14–1 Creating a Key for the AES Algorithm

In the following example, a secret key for the AES algorithm is created. The key is also stored for later decryption. AES mechanisms use a 128-bit key. The key is expressed as 16 bytes in the dd command.

% ls -al ~/keyf
drwx------   2 jdoe  staff        512 May 3 11:32 ./
% dd if=/dev/urandom of=$HOME/keyf/05.07.aes16 bs=16  count=1
% chmod 400 ~/keyf/05.07.aes16

Example 14–2 Creating a Key for the DES Algorithm

In the following example, a secret key for the DES algorithm is created. The key is also stored for later decryption. DES mechanisms use a 64-bit key. The key is expressed as 8 bytes in the dd command.

% dd if=/dev/urandom of=$HOME/keyf/05.07.des8 bs=8  count=1
% chmod 400 ~/keyf/05.07.des8

Example 14–3 Creating a Key for the 3DES Algorithm

In the following example, a secret key for the 3DES algorithm is created. The key is also stored for later decryption. 3DES mechanisms use a 192-bit key. The key is expressed as 24 bytes in the dd command.

% dd if=/dev/urandom of=$HOME/keyf/05.07.3des.24 bs=24 count=1
% chmod 400 ~/keyf/05.07.3des.24

Example 14–4 Creating a Key for the MD5 Algorithm

In the following example, a secret key for the MD5 algorithm is created. The key is also stored for later decryption. The key is expressed as 64 bytes in the dd command.

% dd if=/dev/urandom of=$HOME/keyf/05.07.mack64 bs=64 count=1
% chmod 400 ~/keyf/05.07.mack64

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.

• You can instead use the dd command with the Solaris /dev/urandom device as input. The dd command does not store the key. For the procedure, see How to Generate a Symmetric Key by Using the dd Command.

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.

   • To create and initialize an NSS database, see Example 15–5.

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

   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 for use in an application's key file, such as the /etc/inet/secret/ipseckeys file or IPsec.

     % pktool genkey keystore=file outkey=key-fn \ [keytype=specific-symmetric-algorithm] [keylen=size-in-bits] \ [dir=directory] [print=n]

     keystore

     The value file specifies the file type of storage location for the key.

     outkey=key-fn

     Is the filename when keystore=file.

     keytype=specific-symmetric-algorithm

     For a particular algorithm, specify aes, arcfour, des, or 3des.

     keylen=size-in-bits

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

     dir=directory

     Is the directory path to key-fn. By default, directory is the current directory.

     print=n

     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.

     % pktool genkey label=key-label \ [keytype=specific-symmetric-algorithm] [keylen=size-in-bits] \ [token=token] [sensitive=n] [extractable=y] [print=n]

     label=key-label

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

     keytype=specific-symmetric-algorithm

     For a particular algorithm, specify aes, arcfour, des, or 3des.

     keylen=size-in-bits

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

     token=token

     Is the token name. By default, the token 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=n

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

   • Generate a key and store it in an NSS keystore.

     You must complete Step 1 before using this method.

     % pktool keystore=nss genkey label=key-label \ [keytype=[keytype=specific-symmetric-algorithm] [keylen=size-in-bits] [token=token] \ [dir=directory-path] [prefix=database-prefix]

     keystore

     The value nss specifies the NSS type of storage location for the key.

     label=key-label

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

     keytype=specific-symmetric-algorithm

     For a particular algorithm, specify aes, arcfour, des, or 3des.

     keylen=size-in-bits

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

     token=token

     Is the token name. By default, the token is the NSS internal token.

     dir=directory

     Is the directory path to the NSS database. By default, directory is the current directory.

     prefix=directory

     Is the prefix to the NSS database. The default is no prefix.

     print=n

     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 or the NSS keystore.

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

Example 14–5 Creating a DES Key by Using the pktool Command

In the following example, a secret key for the DES algorithm is created. 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.

DES mechanisms use a 64-bit key. The user who owns the keyfile retrieves the key by using the od command.

% pktool genkey keystore=file outkey=64bit.file1 keytype=des print=y
        Key Value ="a3237b2c0a8ff9b3"
% od -x 64bit.file1
0000000 a323 7b2c 0a8f f9b3

How to Compute a Digest of a File

When you compute a digest of a file, you can check to see that the file has not been tampered with by comparing digest outputs. A digest does not alter the original file.

1. List the available digest algorithms.

   % digest -l md5 sha1 sha256 sha384 sha512

2. Compute the digest of the file and save the digest listing.

   Provide an algorithm with the digest command.

   % digest -v -a algorithm input-file > digest-listing

   -v

   Displays the output in the following format:

   algorithm (input-file) = digest

   -a algorithm

   Is the algorithm to use to compute a digest of the file. Type the algorithm as the algorithm appears in the output of Step 1.

   input-file

   Is the input file for the digest command.

   digest-listing

   Is the output file for the digest command.

Example 14–6 Computing a Digest With the MD5 Mechanism

In the following example, the digest command uses the MD5 mechanism to compute a digest for an email attachment.

% digest -v -a md5 email.attach >>  $HOME/digest.emails.05.07
% cat  ~/digest.emails.05.07
md5 (email.attach) = 85c0a53d1a5cc71ea34d9ee7b1b28b01

When the -v option is not used, the digest is saved with no accompanying information:

% digest -a md5 email.attach >>  $HOME/digest.emails.05.07
% cat  ~/digest.emails.05.07
85c0a53d1a5cc71ea34d9ee7b1b28b01

Example 14–7 Computing a Digest With the SHA1 Mechanism

In the following example, the digest command uses the SHA1 mechanism to provide a directory listing. The results are placed in a file.

% digest -v -a sha1 docs/* > $HOME/digest.docs.legal.05.07
% more ~/digest.docs.legal.05.07
sha1 (docs/legal1) = 1df50e8ad219e34f0b911e097b7b588e31f9b435
sha1 (docs/legal2) = 68efa5a636291bde8f33e046eb33508c94842c38
sha1 (docs/legal3) = 085d991238d61bd0cfa2946c183be8e32cccf6c9
sha1 (docs/legal4) = f3085eae7e2c8d008816564fdf28027d10e1d983

How to Compute a MAC of a File

A message authentication code, or MAC, computes a digest for the file and uses a secret key to further protect the digest. A MAC does not alter the original file.

1. List the available mechanisms.

   % mac -l Algorithm Keysize: Min Max ----------------------------------- des_mac 64 64 sha1_hmac 8 512 md5_hmac 8 512 sha256_hmac 8 512 sha384_hmac 8 1024 sha512_hmac 8 1024

2. Generate a symmetric key of the appropriate length.

   You have two options. You can provide a passphrase from which a key will be generated. Or you can provide a key.

   • If you provide a passphrase, you must store or remember the passphrase. If you store the passphrase online, the passphrase file should be readable only by you.

   • If you provide a key, it must be the correct size for the mechanism. For the procedure, see How to Generate a Symmetric Key by Using the dd Command.

3. Create a MAC for a file.

   Provide a key and use a symmetric key algorithm with the mac command.

   % mac -v -a algorithm [ -k keyfile ] input-file

   -v

   Displays the output in the following format:

   algorithm (input-file) = mac

   -a algorithm

   Is the algorithm to use to compute the MAC. Type the algorithm as the algorithm appears in the output of the mac -l command.

   -k keyfile

   Is the file that contains a key of algorithm-specified length.

   input-file

   Is the input file for the MAC.

Example 14–8 Computing a MAC With DES_MAC and a Passphrase

In the following example, the email attachment is authenticated with the DES_MAC mechanism and a key that is derived from a passphrase. The MAC listing is saved to a file. If the passphrase is stored in a file, the file should not be readable by anyone but the user.

% mac -v -a des_mac email.attach
Enter passphrase: <Type passphrase>
des_mac (email.attach) = dd27870a
% echo "des_mac (email.attach) = dd27870a" >> ~/desmac.daily.05.07

Example 14–9 Computing a MAC With MD5_HMAC and a Key File

In the following example, the email attachment is authenticated with the MD5_HMAC mechanism and a secret key. The MAC listing is saved to a file.

% mac -v -a md5_hmac -k $HOME/keyf/05.07.mack64 email.attach
md5_hmac (email.attach) = 02df6eb6c123ff25d78877eb1d55710c
% echo "md5_hmac (email.attach) = 02df6eb6c123ff25d78877eb1d55710c" \
>> ~/mac.daily.05.07

Example 14–10 Computing a MAC With SHA1_HMAC and a Key File

In the following example, the directory manifest is authenticated with the SHA1_HMAC mechanism and a secret key. The results are placed in a file.

% mac -v -a sha1_hmac \
-k $HOME/keyf/05.07.mack64 docs/* > $HOME/mac.docs.legal.05.07
% more ~/mac.docs.legal.05.07
sha1_hmac (docs/legal1) = 9b31536d3b3c0c6b25d653418db8e765e17fe07a
sha1_hmac (docs/legal2) = 865af61a3002f8a457462a428cdb1a88c1b51ff5
sha1_hmac (docs/legal3) = 076c944cb2528536c9aebd3b9fbe367e07b61dc7
sha1_hmac (docs/legal4) = 7aede27602ef6e4454748cbd3821e0152e45beb4

How to Encrypt and Decrypt a File

When you encrypt a file, the original file is not removed or changed. The output file is encrypted.

For solutions to common errors from the encrypt command, see the section that follows the examples.

1. Create a symmetric key of the appropriate length.

   You have two options. You can provide a passphrase from which a key will be generated. Or you can provide a key.

   • If you provide a passphrase, you must store or remember the passphrase. If you store the passphrase online, the passphrase file should be readable only by you.

   • If you provide a key, it must be the correct size for the mechanism. For the procedure, see How to Generate a Symmetric Key by Using the dd Command.

2. Encrypt a file.

   Provide a key and use a symmetric key algorithm with the encrypt command.

   % encrypt -a algorithm [ -k keyfile ] -i input-file -o output-file

   -a algorithm

   Is the algorithm to use to encrypt the file. Type the algorithm as the algorithm appears in the output of the encrypt -l command.

   -k keyfile

   Is the file that contains a key of algorithm-specified length. The key length for each algorithm is listed, in bits, in the output of the encrypt -l command.

   -i input-file

   Is the input file that you want to encrypt. This file is left unchanged by the command.

   -o output-file

   Is the output file that is the encrypted form of the input file.

Example 14–11 Encrypting and Decrypting With AES and a Passphrase

In the following example, a file is encrypted with the AES algorithm. The key is generated from the passphrase. If the passphrase is stored in a file, the file should not be readable by anyone but the user.

% encrypt -a aes -i ticket.to.ride -o ~/enc/e.ticket.to.ride
Enter passphrase: <Type passphrase>
Re-enter passphrase: Type passphrase again

The input file, ticket.to.ride, still exists in its original form.

To decrypt the output file, the user uses the same passphrase and encryption mechanism that encrypted the file.

% decrypt -a aes -i ~/enc/e.ticket.to.ride -o ~/d.ticket.to.ride
Enter passphrase: <Type passphrase>

Example 14–12 Encrypting and Decrypting With AES and a Key File

In the following example, a file is encrypted with the AES algorithm. AES mechanisms use a key of 128 bits, or 16 bytes.

% encrypt -a aes -k ~/keyf/05.07.aes16 \
-i ticket.to.ride -o ~/enc/e.ticket.to.ride 

The input file, ticket.to.ride, still exists in its original form.

To decrypt the output file, the user uses the same key and encryption mechanism that encrypted the file.

% decrypt -a aes -k ~/keyf/05.07.aes16  \
-i ~/enc/e.ticket.to.ride -o ~/d.ticket.to.ride

Example 14–13 Encrypting and Decrypting With ARCFOUR and a Key File

In the following example, a file is encrypted with the ARCFOUR algorithm. The ARCFOUR algorithm accepts a key of 8 bits (1 byte), 64 bits (8 bytes), or 128 bits (16 bytes).

% encrypt -a arcfour -i personal.txt \
-k ~/keyf/05.07.rc4.8 -o ~/enc/e.personal.txt

To decrypt the output file, the user uses the same key and encryption mechanism that encrypted the file.

% decrypt -a arcfour -i ~/enc/e.personal.txt \
-k ~/keyf/05.07.rc4.8 -o ~/personal.txt

Example 14–14 Encrypting and Decrypting With 3DES and a Key File

In the following example, a file is encrypted with the 3DES algorithm. The 3DES algorithm requires a key of 192 bits, or 24 bytes.

% encrypt -a 3des -k ~/keyf/05.07.des24 \
-i ~/personal2.txt -o ~/enc/e.personal2.txt

To decrypt the output file, the user uses the same key and encryption mechanism that encrypted the file.

% decrypt -a 3des -k ~/keyf/05.07.des24 \
-i ~/enc/e.personal2.txt -o ~/personal2.txt

Troubleshooting

The following messages indicate that the key that you provided to the encrypt command is not permitted by the algorithm that you are using.

• encrypt: unable to create key for crypto operation: CKR_ATTRIBUTE_VALUE_INVALID

• encrypt: failed to initialize crypto operation: CKR_KEY_SIZE_RANGE

If you pass a key that does not meet the requirements of the algorithm, you must supply a better key.

• One option is to use a passphrase. The framework then provides a key that meets the requirements.

• The second option is to pass a key size that the algorithm accepts. For example, the DES algorithm requires a key of 64 bits. The 3DES algorithm requires a key of 192 bits.

Administering the Cryptographic Framework (Task Map)

The following task map points to procedures for administering software and hardware providers in the Solaris Cryptographic Framework.

Administering the Cryptographic Framework

This section describes how to administer the software providers and the hardware providers in the Solaris Cryptographic Framework. Software providers and hardware providers can be removed from use when desirable. For example, you can disable the implementation of an algorithm from one software provider. You can then force the system to use the algorithm from a different software provider.

How to List Available Providers

The Solaris Cryptographic Framework provides algorithms for several types of consumers:

• User-level providers provide a PKCS #11 cryptographic interface to applications that are linked with the libpkcs11 library

• Kernel software providers provide algorithms for IPsec, Kerberos, and other Solaris kernel components

• Kernel hardware providers provide algorithms that are available to kernel consumers and to applications through the pkcs11_kernel library

1. List the providers in a brief format.

   ---

   Note –

   The contents and format of the providers list varies for different Solaris releases. Run the cryptoadm list command on your system to see the providers that your system supports.

   ---

   Only those mechanisms at the user level are available for use by regular users.

   % cryptoadm list user-level providers: /usr/lib/security/$ISA/pkcs11_kernel.so /usr/lib/security/$ISA/pkcs11_softtoken.so kernel software providers: des aes blowfish arcfour sha1 md5 rsa kernel hardware providers: ncp/0

2. List the providers and their mechanisms in the Solaris Cryptographic Framework.

   All mechanisms are listed in the following output. However, some of the listed mechanisms might be unavailable for use. To list only the mechanisms that the administrator has approved for use, see Example 14–16.

   The output is reformatted for display purposes.

   % cryptoadm list -m user-level providers: ===================== /usr/lib/security/$ISA/pkcs11_kernel.so: CKM_MD5,CKM_MD5_HMAC, CKM_MD5_HMAC_GENERAL,CKM_SHA_1,CKM_SHA_1_HMAC,CKM_SHA_1_HMAC_GENERAL, … /usr/lib/security/$ISA/pkcs11_softtoken.so: CKM_DES_CBC,CKM_DES_CBC_PAD,CKM_DES_ECB,CKM_DES_KEY_GEN, CKM_DES3_CBC,CKM_DES3_CBC_PAD,CKM_DES3_ECB,CKM_DES3_KEY_GEN, CKM_AES_CBC,CKM_AES_CBC_PAD,CKM_AES_ECB,CKM_AES_KEY_GEN, … kernel software providers: ========================== des: CKM_DES_ECB,CKM_DES_CBC,CKM_DES3_ECB,CKM_DES3_CBC aes: CKM_AES_ECB,CKM_AES_CBC blowfish: CKM_BF_ECB,CKM_BF_CBC arcfour: CKM_RC4 sha1: CKM_SHA_1,CKM_SHA_1_HMAC,CKM_SHA_1_HMAC_GENERAL md5: CKM_MD5,CKM_MD5_HMAC,CKM_MD5_HMAC_GENERAL rsa: CKM_RSA_PKCS,CKM_RSA_X_509,CKM_MD5_RSA_PKCS,CKM_SHA1_RSA_PKCS swrand: No mechanisms presented. kernel hardware providers: ========================== ncp/0: CKM_DSA,CKM_RSA_X_509,CKM_RSA_PKCS,CKM_RSA_PKCS_KEY_PAIR_GEN, CKM_DH_PKCS_KEY_PAIR_GEN,CKM_DH_PKCS_DERIVE,CKM_EC_KEY_PAIR_GEN, CKM_ECDH1_DERIVE,CKM_ECDSA

Example 14–15 Finding the Existing Cryptographic Mechanisms

In the following example, all mechanisms that the user-level library, pkcs11_softtoken, offers are listed.

% cryptoadm list -m provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so
Mechanisms:
CKM_DES_CBC,CKM_DES_CBC_PAD,CKM_DES_ECB,CKM_DES_KEY_GEN,
CKM_DES3_CBC,CKM_DES3_CBC_PAD,CKM_DES3_ECB,CKM_DES3_KEY_GEN,
…
CKM_SSL3_KEY_AND_MAC_DERIVE,CKM_TLS_KEY_AND_MAC_DERIVE

Example 14–16 Finding the Available Cryptographic Mechanisms

Policy determines which mechanisms are available for use. The administrator sets the policy. An administrator can choose to disable mechanisms from a particular provider. The -p option displays the list of mechanisms that are permitted by the policy that the administrator has set.

% cryptoadm list -p
user-level providers:
=====================
/usr/lib/security/$ISA/pkcs11_kernel.so: all mechanisms are enabled.
random is enabled.
/usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled.
random is enabled.

kernel software providers:
==========================
des: all mechanisms are enabled.
aes: all mechanisms are enabled.
blowfish: all mechanisms are enabled.
arcfour: all mechanisms are enabled.
sha1: all mechanisms are enabled.
md5: all mechanisms are enabled.
rsa: all mechanisms are enabled.
swrand: random is enabled.

kernel hardware providers:
==========================
ncp/0: all mechanisms are enabled.

How to Add a Software Provider

1. Assume the Primary Administrator role, or become superuser.

   The Primary Administrator role includes the Primary Administrator profile. To create the role and assign the role to a user, see Chapter 2, Working With the Solaris Management Console (Tasks), in System Administration Guide: Basic Administration.

2. List the software providers that are available to the system.

   % cryptoadm list user-level providers: /usr/lib/security/$ISA/pkcs11_kernel.so /usr/lib/security/$ISA/pkcs11_softtoken.so kernel software providers: des aes blowfish arcfour sha1 md5 rsa kernel hardware providers: ncp/0

3. Add the provider's package by using the pkgadd command.

   # pkgadd -d /path/to/package pkginst

   The package must include software that has been signed by a certificate from Sun. To request a certificate from Sun and to sign a provider, see Appendix F, Packaging and Signing Cryptographic Providers, in Oracle Solaris Security for Developers Guide.

   The package should have scripts that notify the cryptographic framework that another provider with a set of mechanisms is available. For information about the packaging requirements, see Appendix F, Packaging and Signing Cryptographic Providers, in Oracle Solaris Security for Developers Guide.

4. Refresh the providers.

   You need to refresh providers if you added a software provider, or if you added hardware and specified policy for the hardware.

   # svcadm refresh svc:/system/cryptosvc

5. Locate the new provider on the list.

   In this case, a new kernel software provider was installed.

   # cryptoadm list … kernel software providers: des aes blowfish arcfour sha1 md5 rsa swrand ecc <-- added provider …

Example 14–17 Adding a User-Level Software Provider

In the following example, a signed PKCS #11 library is installed.

# pkgadd -d /cdrom/cdrom0/SolarisNew
Answer the prompts
# svcadm refresh system/cryptosvc
# cryptoadm list
user-level providers:
==========================
    /usr/lib/security/$ISA/pkcs11_kernel.so
    /usr/lib/security/$ISA/pkcs11_softtoken.so
    /opt/SUNWconn/lib/$ISA/libpkcs11.so.1 <-- added provider

Developers who are testing a library with the cryptographic framework can install the library manually.

# cryptoadm install provider=/opt/SUNWconn/lib/\$ISA/libpkcs11.so.1

For information on getting your provider signed, see Binary Signatures for Third-Party Software.

How to Prevent the Use of a User-Level Mechanism

If some of the cryptographic mechanisms from a library provider should not be used, you can remove selected mechanisms. This procedure uses the DES mechanisms in the pkcs11_softtoken library as an example.

1. Become superuser or assume a role that includes the Crypto Management rights profile.

   To create a role that includes the Crypto Management rights profile and assign the role to a user, see Example 9–7.

2. List the mechanisms that are offered by a particular user-level software provider.

   % cryptoadm list -m provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so /usr/lib/security/$ISA/pkcs11_softtoken.so: CKM_DES_CBC,CKM_DES_CBC_PAD,CKM_DES_ECB,CKM_DES_KEY_GEN, CKM_DES3_CBC,CKM_DES3_CBC_PAD,CKM_DES3_ECB,CKM_DES3_KEY_GEN, CKM_AES_CBC,CKM_AES_CBC_PAD,CKM_AES_ECB,CKM_AES_KEY_GEN, …

3. List the mechanisms that are available for use.

   $ cryptoadm list -p user-level providers: ===================== … /usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled. random is enabled. …

4. Disable the mechanisms that should not be used.

   $ cryptoadm disable provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so \ > mechanism=CKM_DES_CBC,CKM_DES_CBC_PAD,CKM_DES_ECB

5. List the mechanisms that are available for use.

   $ cryptoadm list -p provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so /usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled, except CKM_DES_ECB,CKM_DES_CBC_PAD,CKM_DES_CBC. random is enabled.

Example 14–18 Enabling a User-Level Software Provider Mechanism

In the following example, a disabled DES mechanism is again made available for use.

$ cryptoadm list -m provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so
/usr/lib/security/$ISA/pkcs11_softtoken.so:
CKM_DES_CBC,CKM_DES_CBC_PAD,CKM_DES_ECB,CKM_DES_KEY_GEN,
CKM_DES3_CBC,CKM_DES3_CBC_PAD,CKM_DES3_ECB,CKM_DES3_KEY_GEN,
…
$ cryptoadm list -p provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so
/usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled,
except CKM_DES_ECB,CKM_DES_CBC_PAD,CKM_DES_CBC. random is enabled.
$ cryptoadm enable provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so \
> mechanism=CKM_DES_ECB
$ cryptoadm list -p provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so
/usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled,
except CKM_DES_CBC_PAD,CKM_DES_CBC. random is enabled.

Example 14–19 Enabling All User-Level Software Provider Mechanisms

In the following example, all mechanisms from the user-level library are enabled.

$ cryptoadm enable provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so all
$ cryptoadm list -p provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so
/usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled.
random is enabled.

Example 14–20 Permanently Removing User-Level Software Provider Availability

In the following example, the libpkcs11.so.1 library is removed.

$ cryptoadm uninstall provider=/opt/SUNWconn/lib/\$ISA/libpkcs11.so.1
$ cryptoadm list
user-level providers:
    /usr/lib/security/$ISA/pkcs11_kernel.so
    /usr/lib/security/$ISA/pkcs11_softtoken.so

kernel software providers:
…

How to Prevent the Use of a Kernel Software Provider

If the cryptographic framework provides multiple modes of a provider such as AES, you might remove a slow mechanism from use, or a corrupted mechanism. This procedure uses the AES algorithm as an example.

1. Become superuser or assume a role that includes the Crypto Management rights profile.

   To create a role that includes the Crypto Management rights profile and assign the role to a user, see Example 9–7.

2. List the mechanisms that are offered by a particular kernel software provider.

   $ cryptoadm list -m provider=aes aes: CKM_AES_ECB,CKM_AES_CBC

3. List the mechanisms that are available for use.

   $ cryptoadm list -p provider=aes aes: all mechanisms are enabled.

4. Disable the mechanism that should not be used.

   $ cryptoadm disable provider=aes mechanism=CKM_AES_ECB

5. List the mechanisms that are available for use.

   $ cryptoadm list -p provider=aes aes: all mechanisms are enabled, except CKM_AES_ECB.

Example 14–21 Enabling a Kernel Software Provider Mechanism

In the following example, a disabled AES mechanism is again made available for use.

cryptoadm list -m provider=aes
aes: CKM_AES_ECB,CKM_AES_CBC
$ cryptoadm list -p provider=aes
aes: all mechanisms are enabled, except CKM_AES_ECB.
$ cryptoadm enable provider=aes mechanism=CKM_AES_ECB
$ cryptoadm list -p provider=aes
aes: all mechanisms are enabled.

Example 14–22 Temporarily Removing Kernel Software Provider Availability

In the following example, the AES provider is temporarily removed from use. The unload subcommand is useful to prevent a provider from being loaded automatically while the provider is being uninstalled. For example, the unload subcommand would be used when installing a patch that affects the provider.

$ cryptoadm unload provider=aes

$ cryptoadm list 
…
kernel software providers:
    des
    aes (inactive)
    blowfish
    arcfour
    sha1
    md5
    rsa
    swrand

The AES provider is unavailable until the cryptographic framework is refreshed.

$ svcadm refresh system/cryptosvc

$ cryptoadm list 
…
kernel software providers:
    des
    aes
    blowfish
    arcfour
    sha1
    md5
    rsa
    swrand

If a kernel consumer is using the kernel software provider, the software is not unloaded. An error message is displayed and the provider continues to be available for use.

Example 14–23 Permanently Removing Software Provider Availability

In the following example, the AES provider is removed from use. Once removed, the AES provider does not appear in the policy listing of kernel software providers.

$ cryptoadm uninstall provider=aes

$ cryptoadm list 
…
kernel software providers:
    des
    blowfish
    arcfour
    sha1
    md5
    rsa
    swrand

If a kernel consumer is using the kernel software provider, an error message is displayed and the provider continues to be available for use.

Example 14–24 Reinstalling a Removed Kernel Software Provider

In the following example, the AES kernel software provider is reinstalled.

$ cryptoadm install provider=aes mechanism=CKM_AES_ECB,CKM_AES_CBC

$ cryptoadm list 
…
kernel software providers:
    des
    aes
    blowfish
    arcfour
    sha1
    md5
    rsa
    swrand

How to List Hardware Providers

Hardware providers are automatically located and loaded. For more information, see driver.conf(4) man page.

Before You Begin

When you have hardware that expects to be used within the Solaris Cryptographic Framework, the hardware registers with the SPI in the kernel. The framework checks that the hardware driver is signed. Specifically, the framework checks that the object file of the driver is signed with a certificate that Sun issues.

For example, the Sun Crypto Accelerator 6000 board (mca), the ncp driver for the cryptographic accelerator on the UltraSPARC T1 and T2 processors (ncp), and the n2cp driver for the UltraSPARC T2 processors (n2cp) plug hardware mechanisms into the framework.

For information on getting your provider signed, see Binary Signatures for Third-Party Software.

1. List the hardware providers that are available on the system.

   % cryptoadm list … kernel hardware providers: ncp/0

2. List the mechanisms that the chip or the board provides.

   % cryptoadm list -m provider=ncp/0 ncp/0: CKM_DSA,CKM_RSA_X_509,CKM_RSA_PKCS,CKM_RSA_PKCS_KEY_PAIR_GEN, CKM_DH_PKCS_KEY_PAIR_GEN,CKM_DH_PKCS_DERIVE,CKM_EC_KEY_PAIR_GEN, CKM_ECDH1_DERIVE,CKM_ECDSA

3. List the mechanisms that are available for use on the chip or the board.

   % cryptoadm list -p provider=ncp/0 ncp/0: all mechanisms are enabled.

How to Disable Hardware Provider Mechanisms and Features

You can selectively disable mechanisms and the random number feature from a hardware provider. To enable them again, see Example 14–25. The hardware in this example, the Sun Crypto Accelerator 1000 board, provides a random number generator.

1. Become superuser or assume a role that includes the Crypto Management rights profile.

   To create a role that includes the Crypto Management rights profile and assign the role to a user, see Example 9–7.

2. Choose the mechanisms or feature to disable.

   List the hardware provider.

   # cryptoadm list ... Kernel hardware providers: dca/0

   • Disable selected mechanisms.

     # cryptoadm list -m provider=dca/0 dca/0: CKM_RSA_PKCS, CKM_RSA_X_509, CKM_DSA, CKM_DES_CBC, CKM_DES3_CBC random is enabled. # cryptoadm disable provider=dca/0 mechanism=CKM_DES_CBC,CKM_DES3_CBC # cryptoadm list -p provider=dca/0 dca/0: all mechanisms are enabled except CKM_DES_CBC,CKM_DES3_CBC. random is enabled.

   • Disable the random number generator.

     # cryptoadm list -p provider=dca/0 dca/0: all mechanisms are enabled. random is enabled. # cryptoadm disable provider=dca/0 random # cryptoadm list -p provider=dca/0 dca/0: all mechanisms are enabled. random is disabled.

   • Disable all mechanisms. Do not disable the random number generator.

     # cryptoadm list -p provider=dca/0 dca/0: all mechanisms are enabled. random is enabled. # cryptoadm disable provider=dca/0 mechanism=all # cryptoadm list -p provider=dca/0 dca/0: all mechanisms are disabled. random is enabled.

   • Disable every feature and mechanism on the hardware.

     # cryptoadm list -p provider=dca/0 dca/0: all mechanisms are enabled. random is enabled. # cryptoadm disable provider=dca/0 all # cryptoadm list -p provider=dca/0 dca/0: all mechanisms are disabled. random is disabled.

Example 14–25 Enabling Mechanisms and Features on a Hardware Provider

In the following examples, disabled mechanisms on a piece of hardware are selectively enabled.

# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled except CKM_DES_ECB,CKM_DES3_ECB

.
random is enabled.
# cryptoadm enable provider=dca/0 mechanism=CKM_DES3_ECB
# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled except CKM_DES_ECB. 
random is enabled.

In the following example, only the random generator is enabled.

# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled, except CKM_MD5,CKM_MD5_HMAC,…. 
random is disabled.
# cryptoadm enable provider=dca/0 random
# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled, except CKM_MD5,CKM_MD5_HMAC,….
random is enabled.

In the following example, only the mechanisms are enabled. The random generator continues to be disabled.

# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled, except CKM_MD5,CKM_MD5_HMAC,….
random is disabled.
# cryptoadm enable provider=dca/0 mechanism=all
# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled. random is disabled.

In the following example, every feature and mechanism on the board is enabled.

# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled, except CKM_DES_ECB,CKM_DES3_ECB.
random is disabled.
# cryptoadm enable provider=dca/0 all
# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled. random is enabled.

How to Refresh or Restart All Cryptographic Services

By default, the Solaris Cryptographic Framework is enabled. When the kcfd daemon fails for any reason, the service management facility can be used to restart cryptographic services. For more information, see the smf(5) and svcadm(1M) man pages. For the effect on zones of restarting cryptographic services, see Cryptographic Services and Zones.

1. Check the status of cryptographic services.

   % svcs cryptosvc STATE STIME FMRI offline Dec_09 svc:/system/cryptosvc:default

2. Become superuser or assume an equivalent role to enable cryptographic services.

   Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map).

   # svcadm enable svc:/system/cryptosvc

Example 14–26 Refreshing Cryptographic Services

In the following example, cryptographic services are refreshed in the global zone. Therefore, kernel-level cryptographic policy in every non-global zone is also refreshed.

# svcadm refresh system/cryptosvc

Chapter 15 Solaris Key Management Framework

Starting in the Solaris 10 8/07 release, the Key Management Framework (KMF) 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.

• Managing Public Key Technologies

• Key Management Framework Utilities

• Using the Key Management Framework (Tasks)

Managing Public Key Technologies

The Key Management Framework (KMF) provides a unified approach to managing public key technologies (PKI). The Solaris OS 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 – This command manages PKI objects, such as certificates, in a variety of keystores.

• kmfcfg command – This command manages the PKI policy database

  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 – This 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 manages the policy, keys, and certificates for three public key technologies:

• Tokens from PKCS #11 providers, that is, from the Solaris Cryptographic Framework

• NSS, that is, Network Security Services

• OpenSSL, a file-based keystore

The kmfcfg tool can create, modify, or delete KMF policy entries. 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 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.

• 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:

• Generate a passphrase for the keystore.

• Generate a passphrase 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 (Task Map)

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

Using the Key Management Framework (Tasks)

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

How to Create a Certificate by Using the pktool gencert 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.

1. Generate a self-signed certificate.

   % pktool gencert [keystore=keystore] label=label-name \ subject=subject-DN serial=hex-serial-number

   keystore=keystore

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

   label=label-name

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

   subject=subject-DN

   Is the distinguished name for the certificate.

   serial=hex-serial-number

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

2. 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 n. ...

   This command lists all certificates in the keystore. In the following example, the keystore contains one certificate only.

Example 15–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.

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

% pktool list
Found 1 certificates.
1. (X.509 certificate)
      Label: My Cert
      ID: 12:82:17:5f:80:78:eb:44:8b:98:e3:3c:11:c0:32:5e:b6:4c:ea:eb
      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: 0x01

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 Example 15–4.

1. Import the certificate.

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

2. If you are importing private PKI objects, provide passwords when prompted.

   1. At the prompt, provide 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

3. 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 15–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
Found 1 certificates.
1. (X.509 certificate)
        Label: GraceCert
        ID: 12:82:17:5f:80:78:eb:44:8b:98:e3:3c:11:c0:32:5e:b6:4c:ea:eb
        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: 0x01

Example 15–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
Found 1 certificates.
1. (X.509 certificate)
        Label: TheirCompany Root Cert
        ID: 21:ae:83:98:24:d1:1f:cb:65:5b:48:75:7d:02:47:cf:98:1f:ec:a0
        Subject: C=US, O=TheirCompany, OU=Security, CN=TheirCompany Root CA
        Issuer: C=US, O=TheirCompany, OU=Security, CN=TheirCompany Root CA
        Serial: 0x01

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.

1. 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. ...

2. Export the keys and certificate.

   Use the keystore and label from the pktool list command. Provide a file name for the export file. When the name contains a space, surround the name with double quotes.

   % pktool export keystore=keystore outfile=outfile-name label=label-name

3. 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 15–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
Found 1 certificates.
1. (X.509 certificate)
      Label: My Cert
      ID: 12:82:17:5f:80:78:eb:44:8b:98:e3:3c:11:c0:32:5e:b6:4c:ea:eb
      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: 0x01

% 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 Generate a Passphrase by Using the pktool setpin 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 Example 15–4.

1. Generate a passphrase for access to a keystore.

   % pktool setpin keystore=nss|pkcs11 dir=directory

2. Answer the prompts.

   If the keystore does not have a password already set, press the Return key to create the password.

   Enter current token passphrase: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.

Example 15–5 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:    has8n0NdaH
Re-enter new passphrase:  has8n0NdaH
Passphrase changed.