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) RC4ARCFOUR kernel provider usingcryptographic framework task map task mapscryptographic framework task mapsusing the cryptographic framework cryptographic frameworktask maps The following task map points to tasks for using the cryptographic framework.Task Description For Instructions Protect individual files or sets of files Ensures that file content has not been tampered with. Prevents files from being read by intruders. These procedures can be done by ordinary users. Protecting Files With the Solaris Cryptographic Framework (Task Map) Administer the framework Adds, configures, and removes software providers. Disables and enables hardware provider mechanisms. These procedures are administrative procedures. Administering the Cryptographic Framework (Task Map) Sign a provider Enables a provider to be added to the Solaris Cryptographic Framework. These procedures are developer procedures. Appendix F, Packaging and Signing Cryptographic Providers, in Solaris Security for Developers Guide. encryptingfiles hashingfiles filesencrypting filessecurityencryption fileshashing task mapsprotecting files with cryptographic mechanisms protectingfiles with cryptographic framework user proceduresencrypting files 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.Task Description For Instructions Generate a symmetric key Generates a random key for use with algorithms that the user specifies. How to Generate a Symmetric Key by Using the dd Command Generates a key of user-specified length. Optionally, stores the key in a file, a PKCS #11 keystore, or an NSS keystore. How to Generate a Symmetric Key by Using the pktool Command Provide a checksum that ensures the integrity of a file Verifies that the receiver's copy of a file is identical to the file that was sent. How to Compute a Digest of a File Protect a file with a message authentication code (MAC) Verifies to the receiver of your message that you were the sender. How to Compute a MAC of a File Encrypt a file, and then decrypt the encrypted file Protects the content of files by encrypting the file. Provides the encryption parameters to decrypt the file. How to Encrypt and Decrypt a File 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.generatingsymmetric key using the dd command generatingrandom numberusing the dd command encryptiongenerating symmetric keyusing the dd command computingsecret key keysgenerating symmetric keyusing the dd command devices/dev/urandom device /dev/urandom device secret keyscreating creatingsecret keysfor encryption secret keysgeneratingusing the dd command random numbersdd command dd commandgenerating secret keys user proceduresgenerating a symmetric keyusing the dd command usingdd 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. To create the key, you have three options:If your site has a random number generator, use the generator. If you want to generate the key and store it, see How to Generate a Symmetric Key by Using the pktool Command. Otherwise, use this procedure. This procedure requires that you provide the key size in bites. In contrast, the pktool command determines the correct key size according to the algorithm that you specify. Determine the key length that your algorithm requires.encrypt commandsyntaxl optionencrypt commandList 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 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. Generate the symmetric key.% dd if=/dev/urandom of=keyfile bs=n count=nif=fileIs the input file. For a random key, use the /dev/urandom file. of=keyfileIs the output file that holds the generated key. bs=nIs the key size in bytes. For the length in bytes, divide the key length in bits by 8. count=nIs the count of the input blocks. The number for n should be 1. Store your key in a protected directory.The key file should not be readable by anyone but the user.% chmod 400 keyfile 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 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 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 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 computingsecret key creatingsecret keysfor encryption encryptiongenerating symmetric keyusing the pktool command generatingsymmetric key using the pktool command keysgenerating symmetric keyusing the pktool command secret keysgeneratingusing the pktool command generatingrandom numberusing the pktool command secret keyscreating random numberspktool command pktool commandgenerating secret keys usingpktool command user proceduresgenerating a symmetric keyusing the pktool command usersgenerating a symmetric key 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. 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. 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=generic|specific-symmetric-algorithm] [keylen=size-in-bits] \ [dir=directory] [print=n]keystoreThe value file specifies the file type of storage location for the key. outkey=key-fnIs the filename when keystore=file. keytype=specific-symmetric-algorithmFor a symmetric key of any length, the value is generic. For a particular algorithm, specify aes, arcfour, des, or 3des. keylen=size-in-bitsIs the length of the key in bits. The number must be divisible by 8. Do not specify for des or 3des. dir=directoryIs the directory path to key-fn. By default, directory is the current directory. print=nPrints 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=generic|specific-symmetric-algorithm] [keylen=size-in-bits] [token=token] \ [sensitive=n] [extractable=y] [print=n]label=key-labelIs a user-specified label for the key. The key can be retrieved from the keystore by its label. keytype=specific-symmetric-algorithmFor a symmetric key of any length, the value is generic. For a particular algorithm, specify aes, arcfour, des, or 3des. keylen=size-in-bitsIs the length of the key in bits. The number must be divisible by 8. Do not specify for des or 3des. token=tokenIs the token name. By default, the token is Sun Software PKCS#11 softtoken. sensitive=nSpecifies 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=ySpecifies that the key can be extracted from the keystore. Specify n to prevent the key from being extracted. print=nPrints 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=generic|specific-symmetric-algorithm] [keylen=size-in-bits] [token=token] \ [dir=directory-path] [prefix=database-prefix]keystoreThe value nss specifies the NSS type of storage location for the key. label=key-labelIs a user-specified label for the key. The key can be retrieved from the keystore by its label. keytype=specific-symmetric-algorithmFor a symmetric key of any length, the value is generic. For a particular algorithm, specify aes, arcfour, des, or 3des. keylen=size-in-bitsIs the length of the key in bits. The number must be divisible by 8. Do not specify for des or 3des. token=tokenIs the token name. By default, the token is the NSS internal token. dir=directoryIs the directory path to the NSS database. By default, directory is the current directory. prefix=directoryIs the prefix to the NSS database. The default is no prefix. print=nPrints the key to the terminal window. By default, the value of print is n. 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) 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.# pktool setpin Create new passphrase:easily-remembered-hard-to-detect-password Re-enter new passphrase:Retype password Passphrase changed. % pktool genkey label=specialappkey keytype=generic keylen=1024 Enter PIN for Sun Software PKCS#11 softtoken :Type password % pktool list objtype=key Enter PIN for Sun Software PKCS#11 softtoken :Type password Found 1 keys. Key #1 - symmetric: specialappkey (1024 bits) 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 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 and destroys the original files.First, the administrator creates and displays the keys that the IPsec policy requires:# pktool genkey keystore=file outkey=ipencrin1 keytype=generic keylen=192 print=y Key Value ="294979e512cb8e79370dabecadc3fcbb849e78d2d6bd2049" # pktool genkey keystore=file outkey=ipencrout1 keytype=generic keylen=192 print=y Key Value ="9678f80e33406c86e3d1686e50406bd0434819c20d09d204" # pktool genkey keystore=file outkey=ipspi1 keytype=generic keylen=32 print=y Key Value ="acbeaa20" # pktool genkey keystore=file outkey=ipspi2 keytype=generic keylen=32 print=y Key Value ="19174215" # pktool genkey keystore=file outkey=ipmd51 keytype=generic keylen=64 print=y Key Value ="438c3ad2cec9a3621e90462d11ca7d2f" # pktool genkey keystore=file outkey=ipmd52 keytype=generic keylen=64 print=y Key Value ="a61319630cf2abde7609ce24de3d029f" 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 0xacbeaa20 \ src 192.168.1.1 dst 192.168.2.1 \ encr_alg 3des auth_alg md5 \ encrkey 294979e512cb8e79370dabecadc3fcbb849e78d2d6bd2049 \ authkey 438c3ad2cec9a3621e90462d11ca7d2f ## ## for inbound packets add esp spi 0x19174215 \ src 192.168.2.1 dst 192.168.1.1 \ encr_alg 3des auth_alg md5 \ encrkey 9678f80e33406c86e3d1686e50406bd0434819c20d09d204 \ authkey a61319630cf2abde7609ce24de3d029f 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 ipmd51 ipmd52 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. new featurescommandsdigest computingdigest of a file digestscomputing for file filescomputing digests of securitycomputing digest of files userscomputing digest of files usingdigest command digestsof files creatingfile digests filescomputing a digest filesverifying integrity with digest filesdigest of user procedurescomputing 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. digest commandsyntaxl optiondigest commandList the available digest algorithms.% digest -l sha1 md5 sha256 sha384 sha512 a optiondigest commandv optiondigest commandCompute the digest of the file and save the digest listing.Provide an algorithm with the digest command.% digest -v -a algorithm input-file > digest-listingvDisplays the output in the following format:algorithm (input-file) = digest a algorithmIs 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-fileIs the input file for the digest command. digest-listingIs the output file for the digest command. digestsof filesfilescomputing digests ofdigest commandexampleviewingdigest of a fileIn 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) = 85c0a53d1a5cc71ea34d9ee7b1b28b01When 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 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 new featurescommandsmac computingMAC of a file message authentication code (MAC)computing for file filescomputing MAC of securitycomputing MAC of files userscomputing MAC of files usingmac command user procedurescomputing 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. mac commandsyntaxl optionmac commandList the available mechanisms.% 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 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.passphrasesmac commandIf 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. You can also use the pktool command. For the procedure and some examples, see How to Generate a Symmetric Key by Using the pktool Command. a optionmac commandv optionmac commandk optionmac commandCreate a MAC for a file.Provide a key and use a symmetric key algorithm with the mac command.% mac [-v] -a algorithm [-k keyfile | -K key-label [-T token]] input-filevDisplays the output in the following format:algorithm (input-file) = mac a algorithmIs the algorithm to use to compute the MAC. Type the algorithm as the algorithm appears in the output of the mac -l command. k keyfileIs the file that contains a key of algorithm-specified length. K key-labelK optionmac commandIs the label of a key in the PKCS #11 keystore. T tokenT optionmac commandIs the token name. By default, the token is Sun Software PKCS#11 softtoken. Is used only when the K key-label option is used. input-fileIs the input file for the MAC. passphrasesusing for MAC 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 key: <Type passphrase> des_mac (email.attach) = dd27870a % echo "des_mac (email.attach) = dd27870a" >> ~/desmac.daily.05.07 keysusing for MAC viewingMAC of a 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 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 In the following example, the directory manifest is authenticated with the SHA1_HMAC mechanism and a secret key. The results are placed in the user's PKCS #11 keystore. The user initially created the keystore and the password to the keystore by using the pktool setpin command.% mac -a sha1_hmac -K legaldocs0507 docs/* Enter pin for Sun Software PKCS#11 softtoken:Type passwordTo retrieve the MAC from the keystore, the user uses the verbose option, and provides the key label and the name of the directory that was authenticated.% mac -v -a sha1_hmac -K legaldocs0507 docs/* Enter pin for Sun Software PKCS#11 softtoken:Type password sha1_hmac (docs/legal1) = 9b31536d3b3c0c6b25d653418db8e765e17fe07a sha1_hmac (docs/legal2) = 865af61a3002f8a457462a428cdb1a88c1b51ff5 sha1_hmac (docs/legal3) = 076c944cb2528536c9aebd3b9fbe367e07b61dc7 sha1_hmac (docs/legal4) = 7aede27602ef6e4454748cbd3821e0152e45beb4 new featurescommandsencrypt encryptingencrypt command filesencrypting securityencrypting files usersencrypting files usingencrypt command encryptingfiles user proceduresdecrypting files 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. Create a symmetric key of the appropriate length.passphrasesencrypt commandYou 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. You can also use the pktool command. For the procedure and some examples, see How to Generate a Symmetric Key by Using the pktool Command. a optionencrypt commandi optionencrypt commandk optionencrypt commando optionencrypt commandEncrypt a file.Provide a key and use a symmetric key algorithm with the encrypt command.% encrypt -a algorithm [-v] \ [-k keyfile | -K key-label [-T token]] [-i input-file] [-o output-file]a algorithmIs the algorithm to use to encrypt the file. Type the algorithm as the algorithm appears in the output of the encrypt -l command. k keyfileIs 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. K key-labelK optionencrypt commandIs the label of a key in the PKCS #11 keystore. T tokenT optionencrypt commandIs the token name. By default, the token is Sun Software PKCS#11 softtoken. Is used only when the K key-label option is used. i input-fileIs the input file that you want to encrypt. This file is left unchanged by the command. o output-fileIs the output file that is the encrypted form of the input file. In the following example, a user creates and stores an AES key in an existing PKCS #11 keystore for use in encryption and decryption. The user can verify that the key exists and can use the key, but cannot view the key itself.% pktool genkey label=MyAESkeynumber1 keytype=aes keylen=256 Enter PIN for Sun Software PKCS#11 softtoken :Type password % pktool list objtype=key Enter PIN for Sun Software PKCS#11 softtoken :<Type password> Found 1 key Key #1 - Sun Software PKCS#11 softtoken: MyAESkeynumber1 (256)To use the key to encrypt a file, the user retrieves the key by its label.% encrypt -a aes -K MyAESkeynumber1 -i encryptthisfile -o encryptedthisfileTo decrypt the encryptedthisfile file, the user retrieves the key by its label.% decrypt -a aes -K MyAESkeynumber1 -i encryptedthisfile -o sameasencryptthisfile decryptingfiles filesdecrypting decrypt commandsyntax passphrasesstoring safelystoringpassphraseIn 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 key: <Type passphrase>The input file, ticket.to.ride, still exists in its original form.new featurescommandsdecryptTo 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 key: <Type passphrase> 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 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.txtTo 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 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.txtTo 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 cryptographic frameworkerror messagestroubleshootingencrypt commanderror messagesencrypt commandtroubleshootingencrypt commandencrypt commandtroubleshootingencrypt commanderror messagesThe 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. task mapsadministering cryptographic framework administeringcryptographic framework task map The following task map points to procedures for administering software and hardware providers in the Solaris Cryptographic Framework.Task Description For Instructions List the providers in the Solaris Cryptographic Framework Lists the algorithms, libraries, and hardware devices that are available for use in the Solaris Cryptographic Framework. How to List Available Providers Add a software provider Adds a PKCS #11 library or a kernel module to the Solaris Cryptographic Framework. The provider must be signed. How to Add a Software Provider Prevent the use of a user-level mechanism Removes a software mechanism from use. The mechanism can be enabled again. How to Prevent the Use of a User-Level Mechanism Temporarily disable mechanisms from a kernel module Temporarily removes a mechanism from use. Usually used for testing. How to Prevent the Use of a Kernel Software Provider Uninstall a provider Removes a kernel software provider from use. Example 14–27 List available hardware providers Shows the attached hardware, shows the mechanisms that the hardware provides, and shows which mechanisms are enabled for use. How to List Hardware Providers Disable mechanisms from a hardware provider Ensures that selected mechanisms on a hardware accelerator are not used. How to Disable Hardware Provider Mechanisms and Features Restart or refresh cryptographic services Ensures that cryptographic services are available. How to Refresh or Restart All Cryptographic Services usingcryptoadm commandnew featurescommandscryptoadmThis 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.listingavailable providers in cryptographic framework providerslisting in cryptographic framework cryptographic frameworklisting providers listingproviders in the cryptographic framework displayingproviders in the cryptographic framework cryptographic frameworklisting providers algorithmslisting in the cryptographic framework 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 cryptoadm commandlisting providersARCFOUR kernel providerAES kernel providerBlowfish encryption algorithmkernel providerDES encryptionkernel providerRSA kernel providerSHA1 kernel providerMD5 encryption algorithmkernel providerpkcs11_kernel.so user-level providerpkcs11_softtoken.so user-level providerlibrariesuser-level providerskernel providerslistingList the providers in a brief format.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: dca/0 List the providers and their mechanisms in the Solaris Cryptographic Framework.viewingcryptographic mechanismsexistingAll 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–20.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: ========================== dca/0: CKM_RSA_PKCS, CKM_RSA_X_509, CKM_DSA, CKM_DES_CBC, CKM_DES3_CBC viewingcryptographic mechanismsexistingviewingexisting cryptographic mechanismsIn 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 /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_SSL3_KEY_AND_MAC_DERIVE,CKM_TLS_KEY_AND_MAC_DERIVE viewingcryptographic mechanismsavailableviewingavailable cryptographic mechanismsPolicy 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: ========================== dca/0: all mechanisms are enabled. random is enabled. addingsoftware provider providersadding software provider addingplugins to cryptographic framework svcadm commandrefreshing cryptographic framework 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. 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 swrand kernel hardware providers: dca/0 pkgadd commandinstalling third-party providersAdd the provider's package by using the pkgadd command.# pkgadd -d /path/to/package pkginstThe 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 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 Solaris Security for Developers Guide. Refresh the providers.service management facilityrefreshing cryptographic frameworkYou 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 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 … addinguser-level software provider providersadding user-level software provider providersadding library addinglibrary plugin PKCS #11 libraryadding as 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 providercryptoadm commandinstalling PKCS #11 librarycryptoadm install commandinstalling PKCS #11 libraryinstall subcommandcryptoadm commandDevelopers who are testing a library with the cryptographic framework can install the library manually.# cryptoadm install provider=/opt/SUNWconn/lib/'$ISA'/libpkcs11.so.1 cryptoadm commanddisabling cryptographic mechanismsdisablingcryptographic mechanismsIf 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. Crypto Management (RBAC)use of rights profileBecome 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. cryptoadm commandm optionm optioncryptoadm commandList 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, … cryptoadm commandp optionp optioncryptoadm commandList 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. … 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 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. 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. enablingcryptographic mechanismsIn 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. removingcryptographic providersuninstallingcryptographic providersIn 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: … preventingkernel software provider use providerspreventing use of kernel software provider cryptoadm commanddisabling cryptographic mechanismsremovingcryptographic providersIf 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. Crypto Management (RBAC)use of rights profileBecome 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. cryptoadm commandm optionm optioncryptoadm commandviewingcryptographic mechanismsavailableviewingavailable cryptographic mechanismsviewingcryptographic mechanismsexistingviewingexisting cryptographic mechanismsList the mechanisms that are offered by a particular kernel software provider.$ cryptoadm list -m provider=aes aes: CKM_AES_ECB,CKM_AES_CBC List the mechanisms that are available for use.$ cryptoadm list -p provider=aes aes: all mechanisms are enabled. cryptoadm commandp optionp optioncryptoadm commandDisable the mechanism that should not be used.$ cryptoadm disable provider=aes mechanism=CKM_AES_ECB List the mechanisms that are available for use.$ cryptoadm list -p provider=aes aes: all mechanisms are enabled, except CKM_AES_ECB. enablingkernel software provider use providersrestoring use of kernel software provider cryptoadm commandrestoring kernel software provider restoringcryptographic providers 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. removingsoftware providerstemporarilyIn 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 swrandThe 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 swrandIf 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. removingsoftware providerspermanentlyIn 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 swrandIf a kernel consumer is using the kernel software provider, an error message is displayed and the provider continues to be available for use. removingsoftware providerspermanentlyIn 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 listinghardware providers providerslisting hardware providers hardware providerslisting listingcryptographic framework providers hardwarelisting attached hardware accelerators hardware providersloadingHardware providers are automatically located and loaded. For more information, see driver.conf4 man page. When you add 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. List the hardware providers that are available on the system.% cryptoadm list … kernel hardware providers: dca/0 List the mechanisms that the board provides.% cryptoadm list -m provider=dca/0 dca/0: CKM_RSA_PKCS, CKM_RSA_X_509, CKM_DSA, CKM_DES_CBC, CKM_DES3_CBC List the mechanisms that are available for use on the board.% cryptoadm list -p provider=dca/0 dca/0: all mechanisms are enabled. random is enabled. providersdisabling hardware mechanisms hardware providersdisabling cryptographic mechanisms cryptoadm commanddisabling hardware mechanisms disablinghardware mechanisms preventinguse of hardware mechanism mechanismsdisabling all on hardware provider You can selectively disable mechanisms and the random number feature from a hardware provider. To enable them again, see Example 14–29. List the mechanisms and features that are available from the board.% cryptoadm list -p provider=dca/0 dca/0: all mechanisms are enabled. random is enabled. 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. Choose the mechanisms or feature to disable: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. hardware providersenabling mechanisms and features onmechanismsenabling some on hardware provideraddinghardware provider mechanisms and featuresenablingmechanisms and features on hardware providerIn 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. service management facilityrestarting cryptographic framework svcadm commandenabling cryptographic framework svcs commandlisting cryptographic services restartingcryptographic services cryptographic frameworkrestarting refreshingcryptographic services cryptographic frameworkrefreshing cryptographic frameworkzones and zonescryptographic services and new featurescommandskcfd kcfd daemon 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 smf5 and svcadm1M man pages. For the effect on zones of restarting cryptographic services, see Cryptographic Services and Zones. Check the status of cryptographic services.% svcs \*cryptosvc\* STATE STIME FMRI offline Dec_09 svc:/system/cryptosvc:default 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 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