Huie-Ying Lee wrote:
> Hi, all:
>
> This proposal is about resolving the following 2 enhancement requests:
> -RFE 4868006 (encrypt(1) and mac(1) needs to support token objects)
> -RFE 6517162 (pktool genkey needs to support generic secret key)
>
> My preliminary proposal has been reviewed by the KMF core team. Below is
> the updated design and I would appreciate any comments by next
> Tuesday, Jan/30.
>
> Thanks,
> Huie-Ying
The most useful way to deal with secret symmetric keys is to allow them
to be used with key wrapping facilities (e.g. import a session key
wrapped with one's one public key -- needing the secured private key to
get at it) or with key agreement algorithms like Diffie-Hellman.
Unless your design supports one or the other of these, I don't see much
value in secured (as in a hard token) symmetric keys.
Am I missing something?
-- Garrett
>
> ---------------------------------cut here
> ----------------------------------------
> ======================
> Background
> ======================
> About 3 years ago, the Solaris EF team discussed about a possible
> enhancement to the encrypt/decrypt/mac commands to support token objects.
> A RFE(4868006) was submitted, but it was not implemented due to lack of
> a convenient tool that a user can use to generate a token key object
> before.
>
> With the newly improved KMF/pktool command integrated in ONNV_53, I
> think that
> implementing this enhancement now can provide some real benefit to users.
> A user can use the "pktool genkey" command to create a token key in a
> pkcs11
> keystore first, then use this pre-generated token key *anytime* later
> to perform
> encryption, descryption or MAC operation with the new
> encrypt/descrypt/mac command.
> This provides a higher degree of security, because the key is safely
> stored in
> a keystore which can be a hardware. Please noted that an example of
> usage is
> provided at the end of this email.
>
> =========================================================
> Updated CLI's for the encrypt, decrypt, and mac commands
> =========================================================
> To support token objects in these 3 commands, 2 new options are added:
>
> -K keylabel -T token[:manuf[:serial]]
>
> These 2 options are used to identify the symmetric token key in the
> token.
> If the token keystore is the Solaris Softtoken keystore, -T can be
> omitted.
>
> The diff files between the original man pages and the updated man pages
> are attached:
> - encrypt.1.diff for the encrypt and decrypt commands.
> - mac.1.diff for the mac command.
>
>
> ==================================================================
> Updated CLI for the "pktool genkey" command
> ==================================================================
> Because a generic secret key is needed by the MAC command when
> the algorithm is not "des_mac", and the current "pktool genkey"
> command doesn't support that, we need to enhance the "pktool genkey"
> to support a generic secret key as following:
>
> pktool genkey [keystore=pkcs11]
> label=key-label
> [keytype=aes|arcfour|des|3des|generic]
> [keylen=key-size (AES, ARCFOUR or GENERIC only)]
> [token=token[:manuf[:serial]]]
> [sensitive=y|n]
> [extractable=y|n]
>
> To be consistent across all the keystores supported in KMF, a generic
> secret key support will be added for the NSS keystore and the file-based
> keystore also. The diff file between the pktool(1) man page of ONNV_53
> and the updated pktool(1) man page, pktool.1.diff, is attached.
>
> =======================================================
> One typical usage to leverage both KMF and EF
> =======================================================
> The following example illustrates a use case which uses the pktool(1),
> encrypt(1) and decrypt(1) commands together to perform cryptographic
> operations with a 3DES token key.
>
> Step 1. Use the "pktool genkey" command to generate a 3DES token key
> in the pkcs11 softtoken keystore.
>
> $pktool genkey keystore=pkcs11 keytype=3des label=my3deskey
> Enter pin for Sun Software PKCS#11 softtoken : XXXXXXX
>
>
> Step 2. Use the "pktool list" command to see the newly created 3DES
> token key.
>
> $pktool list objtype=key
> Enter pin for Sun Software PKCS#11 softtoken : XXXXXXX
> Found 1 keys.
> Key #1 - Triple-DES: my3deskey (1740352 bits) 192 bits
>
>
> Step 3. Use the new "encrypt" command to encrypt an input file with
> the 3DES token key.
>
> $encrypt -a 3des -K my3deskey -i /etc/my_secret -o encrypt.out
> Enter pin for Sun Software PKCS#11 softtoken : XXXXXXX
>
>
> Step 4: Use the new "decrypt" command to decrypt the encrypted output
> with the 3DES
> token key.
>
> $decrypt -a 3des -K my3deskey -i encrypt.out -o decrypt.out
> Enter pin for Sun Software PKCS#11 softtoken : XXXXXXX
>
>
> Step 5: diff /etc/my_secret decrypt.out
>
> --------------------------------------------------------------------------------------
>
> ------------------------------------------------------------------------
>
> *** encrypt.1.orig Tue Jan 23 15:09:13 2007
> --- encrypt.1.new Tue Jan 23 16:54:57 2007
> ***************
> *** 9,20 ****
> encrypt, decrypt - encrypt or decrypt files
>
> SYNOPSIS
> ! /usr/bin/encrypt -l | -a algorithm [-v] [-k key_file] [-i
> ! input_file] [-o output_file]
>
> ! /usr/bin/decrypt -l | -a algorithm [-v] [-k key_file] [-i
> ! input_file] [-o output_file]
>
> DESCRIPTION
> This utility encrypts or decrypts the given file or stdin
> using the algorithm specified. If no output file is speci-
> --- 9,26 ----
> encrypt, decrypt - encrypt or decrypt files
>
> SYNOPSIS
> ! /usr/bin/encrypt -l
>
> ! /usr/bin/encrypt -a algorithm [-v]
> ! [-k key_file | -K key_label [-T token_spec]]
> ! [-i input_file] [-o output_file]
>
> + /usr/bin/decrypt -l
> +
> + /usr/bin/decrypt -a algorithm [-v]
> + [-k key_file | -K key_label [-T token_spec]]
> + [-i input_file] [-o output_file]
> +
> DESCRIPTION
> This utility encrypts or decrypts the given file or stdin
> using the algorithm specified. If no output file is speci-
> ***************
> *** 84,91 ****
> file, see dd(1M) or System Adminis-
> tration Guide: Security Services.
>
>
> -
> -l Display the list of algorithms
> available on the system. This list
> can change depending on the confi-
> --- 90,98 ----
> file, see dd(1M) or System Adminis-
> tration Guide: Security Services.
>
> + -K key_label Specify the label of a symmetric
> + token key in a PKCS#11 token.
>
> -l Display the list of algorithms
> available on the system. This list
> can change depending on the confi-
> ***************
> *** 105,112 ****
> --- 112,140 ----
> tion, much like viewing a binary
> file can do at times.
>
> + -T token_spec Specify a PKCS#11 token other than
> + the default softtoken object store
> + when -K is used.
>
> + The token_spec has the format of:
>
> + token_name [:manuf_id [:serial_no]]
> +
> + When a token label contains trailing
> + spaces, this option does not require
> + them to be typed as a convenience to
> + the user.
> +
> + Colon separates token identification
> + string. If any of the parts have a
> + literal : char then it needs to be
> + escaped using a backslash (\). If
> + no : is found then the entire string
> + (up to 32 chars) is taken as the
> + token label. If only one : is found
> + then the string is the token label
> + and the manufacturer.
> +
> -v Display verbose information. See
> Verbose.
>
> ***************
> *** 216,221 ****
> --- 244,259 ----
>
> example$ encrypt -a 3des -k des3key -i inputfile -o outputfile
>
> + Example 6: Encrypting an Input File with a DES token key
> +
> + The following example encrypts the inputfile file with a
> + DES token key in the softtoken keystore. The DES token key
> + can be generated with pktool(1).
> +
> + example$ encrypt -a des -K mydeskey \
> + -T "Sun Software PKCS#11 softtoken" -i inputfile \
> + -o outputfile
> +
> EXIT STATUS
> The following exit values are returned:
>
> ***************
> *** 241,247 ****
>
>
> SEE ALSO
> ! digest(1), mac(1), dd(1M), getpassphrase(3C),
> libpkcs11(3LIB), attributes(5), pkcs11_softtoken(5)
>
> System Administration Guide: Security Services
> --- 279,285 ----
>
>
> SEE ALSO
> ! digest(1), mac(1), pktool(1), dd(1M), getpassphrase(3C),
> libpkcs11(3LIB), attributes(5), pkcs11_softtoken(5)
>
> System Administration Guide: Security Services
>
> ------------------------------------------------------------------------
>
> *** mac.1.orig Tue Jan 23 17:01:28 2007
> --- mac.1.new Tue Jan 23 17:16:07 2007
> ***************
> *** 9,16 ****
> mac - calculate message authentication codes of the input
>
> SYNOPSIS
> ! /usr/bin/mac -l | [-v] -a algorithm [-k keyfile] [file...]
>
> DESCRIPTION
> The mac utility calculates the message authentication code
> (MAC) of the given file or files or stdin using the algo-
> --- 9,19 ----
> mac - calculate message authentication codes of the input
>
> SYNOPSIS
> ! /usr/bin/mac -l
>
> + /usr/bin/mac [-v] -a algorithm
> + [-k keyfile | -K key_label [-T token_spec]] [file...]
> +
> DESCRIPTION
> The mac utility calculates the message authentication code
> (MAC) of the given file or files or stdin using the algo-
> ***************
> *** 38,48 ****
> material using getpassphrase(3C).
>
> For information on generating a key file,
> ! see dd(1M) or System Administration Guide:
> ! Security Services.
>
>
>
> -l Displays the list of algorithms available on
> the system. This list can change depending
> on the configuration of the cryptographic
> --- 41,54 ----
> material using getpassphrase(3C).
>
> For information on generating a key file,
> ! see pktool(1), dd(1M) or System
> ! Administration Guide: Security Services.
>
>
> + -K key_label Specify the label of a symmetric token key in
> + a PKCS#11 token.
>
> +
> -l Displays the list of algorithms available on
> the system. This list can change depending
> on the configuration of the cryptographic
> ***************
> *** 49,56 ****
> --- 55,80 ----
> framework. The keysizes are displayed in
> bits.
>
> + -T token_spec Specify a PKCS#11 token other than the default
> + softtoken object store when -K is used.
>
> + The token_spec has the format of:
>
> + token_name [:manuf_id [:serial_no]]
> +
> + When a token label contains trailing spaces,
> + this option does not require them to be typed
> + as a convenience to the user.
> +
> + Colon separates token identification string.
> + If any of the parts have a literal : char then
> + it needs to be escaped using a backslash (\).
> + If no : is found then the entire string (up to
> + 32 chars) is taken as the token label. If only
> + one : is found then the string is the token
> + label and the manufacturer.
> +
> +
> -v Provides verbose information.
>
>
> ***************
> *** 111,116 ****
> --- 135,152 ----
> example$ mac -v -k mykey -a sha1_hmac /export/foo
> sha1_hmac (/export/foo) = 913ced311df10f1708d9848641ca8992f4718057
>
> + Example 3: Getting the Message Authentication Code with a token key
> +
> + The following example gets the message authentication code with
> + a generic token key in the softtoken keystore. The generic token
> + can be generated with pktool(1).
> +
> + example$ encrypt -v -a sha1_hmac -K my_generic_key \
> + -T "Sun Software PKCS#11 softtoken" /export/foo
> + Enter pin for Sun Software PKCS#11 softtoken:
> + sha1_hmac (/etc/foo) = c2ba5c38458c092a68940081240d22b670182968
> +
> +
> EXIT STATUS
> The following exit values are returned:
>
> ***************
> *** 151,157 ****
>
>
> SEE ALSO
> ! digest(1), dd(1M), getpassphrase(3C), libpkcs11(3LIB),
> attributes(5), pkcs11_softtoken(5)
>
> System Administration Guide: Security Services
> --- 187,193 ----
>
>
> SEE ALSO
> ! digest(1), pktool(1), dd(1M), getpassphrase(3C), libpkcs11(3LIB),
> attributes(5), pkcs11_softtoken(5)
>
> System Administration Guide: Security Services
>
> ------------------------------------------------------------------------
>
> *** pktool.1.orig Tue Jan 23 15:55:43 2007
> --- pktool.1.new Tue Jan 23 18:01:57 2007
> ***************
> *** 469,476 ****
>
> pktool genkey [keystore=pkcs11]
> label=key-label
> ! [keytype=aes|arcfour|des|3des]
> ! [keylen=key-size (AES or ARCFOUR only)]
> [token=token[:manuf[:serial]]]
> [sensitive=y|n]
> [extractable=y|n]
> --- 469,476 ----
>
> pktool genkey [keystore=pkcs11]
> label=key-label
> ! [keytype=aes|arcfour|des|3des|generic]
> ! [keylen=key-size (AES, ARCFOUR or GENERIC only)]
> [token=token[:manuf[:serial]]]
> [sensitive=y|n]
> [extractable=y|n]
> ***************
> *** 478,485 ****
>
> pktool genkey keystore=nss
> label=key-label
> ! [keytype=aes|arcfour|des|3des]
> ! [keylen=key-size (AES or ARCFOUR only)]
> [token=token[:manuf[:serial]]]
> [dir=directory-path]
> [prefix=DBprefix]
> --- 478,485 ----
>
> pktool genkey keystore=nss
> label=key-label
> ! [keytype=aes|arcfour|des|3des|generic]
> ! [keylen=key-size (AES, ARCFOUR or GENERIC only)]
> [token=token[:manuf[:serial]]]
> [dir=directory-path]
> [prefix=DBprefix]
> ***************
> *** 486,493 ****
>
> pktool genkey keystore=file
> outkey=key-fn
> ! [keytype=aes|arcfour|des|3des]
> ! [keylen=key-size (AES or ARCFOUR only)]
> [dir=directory-path]
> [print=y|n]
>
> --- 486,493 ----
>
> pktool genkey keystore=file
> outkey=key-fn
> ! [keytype=aes|arcfour|des|3des|generic]
> ! [keylen=key-size (AES, ARCFOUR, or GENERIC only)]
> [dir=directory-path]
> [print=y|n]
>
> ***************
> *** 875,881 ****
> For genkey subcommand, the minimum and maximum bits of
> the symmetric key to generate using AES algorithm are
> 128 and 256; using ARCFOUR algorithm are 8 and 2048. The
> ! default key length for AES and ARCFOUR keys is 128. For
> a DES key or a 3DES key, the key length is fixed and
> this option is ignored if specified.
>
> --- 875,883 ----
> For genkey subcommand, the minimum and maximum bits of
> the symmetric key to generate using AES algorithm are
> 128 and 256; using ARCFOUR algorithm are 8 and 2048. The
> ! minimum bits for a generic secret key is 8 and the
> ! maximum bits is arbitrary. The default key length for
> ! AES, ARCFOUR or generic secret keys is 128. For
> a DES key or a 3DES key, the key length is fixed and
> this option is ignored if specified.
>
> ***************
> *** 891,897 ****
>
>
>
> ! keytype=rsa | dsa | aes | arcfour | des | 3des
>
>
> Specifies the type of the private or symmetric key to
> --- 893,899 ----
>
>
>
> ! keytype=rsa | dsa | aes | arcfour | des | 3des | generic
>
>
> Specifies the type of the private or symmetric key to
> ***************
> *** 905,914 ****
>
>
> For genkey subcommand, the valid symmetric key types
> ! are: aes, arcfour, des or 3des. The default key type is
> ! aes. keyusage=[critical:]usage,usage,usage,...
>
>
>
> Key Usage strings:
> * digitalSignature
> --- 907,917 ----
>
>
> For genkey subcommand, the valid symmetric key types
> ! are: aes, arcfour, des, 3des or generic. The default key
> ! type is aes.
>
>
> + keyusage=[critical:]usage,usage,usage,...
>
> Key Usage strings:
> * digitalSignature
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> crypto-discuss mailing list
> crypto-discuss at opensolaris.org
> http://opensolaris.org/mailman/listinfo/crypto-discuss
>
--
Garrett D'Amore, Principal Software Engineer
Tadpole Computer / Computing Technologies Division,
General Dynamics C4 Systems
http://www.tadpolecomputer.com/
Phone: 951 325-2134 Fax: 951 325-2191
