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. 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.
- 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
- 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=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.
- 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.
- (Optional) If you plan to use a keystore, create it.
- 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]
- 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 symmetric key of any length, the value is generic. 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=generic|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 symmetric key of any length, the value is generic. 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=generic|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 symmetric key of any length, the value is generic. 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.
- (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 Symmetric Key by Using the pktool Command
In the following example, a user creates a PKCS #11 keystore for
the first time, and then generates a large symmetric key for an application.
Finally, the user verifies that the key is in the keystore.
# 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)
Example 14-6 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
Example 14-7 Creating a Symmetric Key for IPsec Security Associations
In the following example, the administrator manually creates the keying material for IPsec
SAs and stores them in files. Then, the administrator copies the keys to
the /etc/inet/secret/ipseckeys file 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.
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.
- List the available digest algorithms.
% digest -l
sha1
md5
sha256
sha384
sha512
- 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-8 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-9 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.
- List 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.
- 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 | -K key-label [-T token]] 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.
- -K key-label
Is the label of a key in the PKCS #11 keystore.
- -T token
Is 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-file
Is the input file for the MAC.
Example 14-10 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 key: <Type passphrase>
des_mac (email.attach) = dd27870a
% echo "des_mac (email.attach) = dd27870a" >> ~/desmac.daily.05.07
Example 14-11 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-12 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
Example 14-13 Computing a MAC With SHA1_HMAC and a Key Label
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 password
To 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
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.
- 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.
- Encrypt 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 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.
- -K key-label
Is the label of a key in the PKCS #11 keystore.
- -T token
Is 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-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-14 Creating an AES Key for Encrypting Your Files
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 encryptedthisfile
To decrypt the encryptedthisfile file, the user retrieves the key by its label.
% decrypt -a aes -K MyAESkeynumber1 -i encryptedthisfile -o sameasencryptthisfile
Example 14-15 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 key: <Type passphrase>
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 key: <Type passphrase>
Example 14-16 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-17 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-18 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.
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.