1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/cmd/symkeyutil/symkey.man Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,182 @@
1.4 +
1.5 +NAME
1.6 + symkeyutil - manage fixed keys in the database
1.7 +
1.8 +SYNOPSIS
1.9 + symkeyutil -H
1.10 + symkeyutil -L [std_opts] [-r]
1.11 + symkeyutil -K [-n name] -t type [-s size] [-i id |-j id_file] [std_opts]
1.12 + symkeyutil -D <[-n name | -i id | -j id_file> [std_opts]
1.13 + symkeyutil -I [-n name] [-t type] [-i id | -j id_file] -k data_file [std_opts]
1.14 + symkeyutil -E <-nname | -i id | -j id_file> [-t type] -k data_file [-r] [std_opts]
1.15 + symkeyutil -U [-n name] [-t type] [-i id | -j id_file] -k data_file <wrap_opts> [std_opts]
1.16 + symkeyutil -W <-n name | -i id | -j id_file> [-t type] -k data_file [-r] <wrap_opts> [std_opts]
1.17 + symkeyutil -M <-n name | -i id | -j id_file> -g target_token [std_opts]
1.18 + std_opts -> [-d certdir] [-P dbprefix] [-p password] [-f passwordFile] [-h token]
1.19 + wrap_opts -> <-w wrap_name | -x wrap_id | -y id_file>
1.20 +
1.21 +DESCRIPTION
1.22 +
1.23 + NSS can store fixed keys as well as asymetric keys in the database. The
1.24 + symkeyutil command can be used to manage these keys.
1.25 +
1.26 + As with certutil, symkeyutil takes two types of arguments, commands and
1.27 + options. Most commands fall into one of two catagories: commands which
1.28 + create keys and commands which extract or destroy keys.
1.29 +
1.30 + Exceptions to these catagories are listed first:
1.31 +
1.32 + -H takes no additional options. It lists a more detailed help message.
1.33 + -L takes the standard set of options. It lists all the keys in the
1.34 + specified token (NSS Internal DB Token is the default). Only the
1.35 + -L option accepts the all option for tokens to list all the fixed
1.36 + keys.
1.37 +
1.38 + Key Creation commands:
1.39 + For these commands, the key type (-t) option is always required.
1.40 + In addition, the -s option may be required for certain key types.
1.41 + The standard set of options may be specified.
1.42 +
1.43 + -K Create a new key using the token key gen function.
1.44 + -I Import a new key from the raw data specified in the data file,
1.45 + specified with the -k options (required). This command may fail on
1.46 + some tokens that don't support direct import of key material.
1.47 + -U Unwrap a new key from an encrypted data file specified with the -k
1.48 + option. The -w, -x, or -y option specifies the unwrapping key.
1.49 + The unwrapping algorithm is selected based on the type of the
1.50 + unwrapping key.
1.51 +
1.52 + Key extraction/destruction options:
1.53 + For these keys, one and only of of the -n, -i, or -j options must be
1.54 + specified. If more than one key matches the -n option, the 'first' key
1.55 + matching will be used. The standard set of options may be specified.
1.56 +
1.57 + -D Delete the key specified by the -n, -i, or -j options.
1.58 + -E Export the key specified by the -n, -i, or -j options and store the
1.59 + contents to a file specified by the -k file (required).
1.60 + This command will seldom work on any token since most keys are
1.61 + protected from export.
1.62 + -W Wrap the key specified by the -n, -i, or -j options and store the
1.63 + encrypted contents to a file specified by the -k file (required).
1.64 + The -w, -x, or -y option specifies the key used to wrap the
1.65 + target key.
1.66 + -M Move the key specified by the -n, -i, or -j options to the token
1.67 + specified by the -g option (required). The new key will have the
1.68 + same attributes as the source key.
1.69 +
1.70 +OPTIONS
1.71 +
1.72 + Standard options are those options that may be used by any command, and
1.73 + whose meaning is the same for all commands.
1.74 +
1.75 + -h token Specify the token which the command will operate on.
1.76 + If -h is not specified the internal token is presumed. In
1.77 + addition the special value 'all' may be used to specify
1.78 + that all tokens should be used. This is only valid for
1.79 + the '-L' command.
1.80 + -d certdir Specify the location of the NSS databases. The default
1.81 + value is platform dependent.
1.82 + -P dbprefix Specify the prefix for the NSS database. The default value
1.83 + is NULL.
1.84 + -p password Specify the password for the token. On the command line.
1.85 + The -p and -f options are mutually exclusive. If
1.86 + neither option is specified, the password would be
1.87 + prompted from the user.
1.88 + -f passwordFile Specify a file that contains the password for the token.
1.89 + This option is mutually exclusive to the -p option.
1.90 +
1.91 + In addition to the standard options are the following command specific
1.92 + options are.
1.93 +
1.94 + -r Opens the NSS databases Read/Write. By default the -L,
1.95 + -E, and -W commands open the database read only. Other
1.96 + commands automatically opens the databases Read/Write and
1.97 + igore this option if it is specified.
1.98 +
1.99 + -n name Specifies the nickname for the key.
1.100 +
1.101 + For the -K, -I, or -U options, name is the name for
1.102 + the new key. If -n is not specified, no name is
1.103 + assumed. There is not check for duplicate names.
1.104 +
1.105 + For the -D, -E, -W, or -M, the name specifies the key to
1.106 + operate on. In this case one andy only one of the -n, -i
1.107 + or -j options should be specifed. It is possible that
1.108 + the -n options specifies and ambiguous key. In that case
1.109 + the 'first' valid key is used.
1.110 +
1.111 + For the -M option, the nickname for the new key is copied
1.112 + from it's original key, even if the original key is
1.113 + specified using -i or -j.
1.114 +
1.115 + -i key id
1.116 + -j key id file These options are equivalent and mutually exclusive.
1.117 + They specify the key id for the file. The -i option
1.118 + specifies the key id on the command line using a hex
1.119 + string. The -j specifies a file to read the raw key
1.120 + id from.
1.121 +
1.122 + For the -K, -I, or -U options, key id is the key id for
1.123 + the new key. If -i or -j is not specified, no key id
1.124 + is assumed. Some tokens may generate their own unique
1.125 + id for the key in this case (but it is not guarrenteed).
1.126 +
1.127 + For the -D, -E, -W, or -M, the key id specifies the key to
1.128 + operate on. In this case one andy only one of the -n, -i
1.129 + or -j options should be specifed.
1.130 +
1.131 + -t type Specifies the key Type for the new key. This option is
1.132 + required for the -K, -I, and -U commands. Valid values
1.133 + are:
1.134 + generic, rc2, rc4, des, des2, des3, cast, cast3,
1.135 + cast5, cast128, rc5, idea, skipjack, baton, juniper,
1.136 + cdmf, aes, camellia
1.137 +
1.138 + Not all tokens support all key types. The generic key
1.139 + type is usually used in MACing and key derivation
1.140 + algorithms. Neither generic nor rc4 keys may be used
1.141 + to wrap other keys. Fixed rc4 keys are dangerous since
1.142 + multiple use of the same stream cipher key to encrypted
1.143 + different data can compromise all data encrypted with
1.144 + that key.
1.145 +
1.146 + -s size Specifies the key size. For most situations the key size
1.147 + is already known and need not be specified. For some
1.148 + algorithms, however, it is necessary to specify the key
1.149 + size when generation or unwrapping the key.
1.150 +
1.151 + -k key file Specifies the name of a file that contains key data to
1.152 + import or unwrap (-I or -U), or the location to store
1.153 + key data or encrypted key data (-E or -W).
1.154 +
1.155 + -g target token Specifies the target token when moving a key (-M). This
1.156 + option is required for the -M command. It is invalid for
1.157 + all other commands.
1.158 +
1.159 +
1.160 +
1.161 + -w wrap name
1.162 + -x wrap key id
1.163 + -y wrap key id file Specifies the wrapping key used int the -U and -W
1.164 + command. Exactly one of these must be specified for the
1.165 + -U or -W commands. Same semantics as the -n, -i, and -j
1.166 + options above.
1.167 +
1.168 +BUGS
1.169 +
1.170 + There is no way display the key id of a key.
1.171 +
1.172 + The -p and -f options only specifies one password. Multiple passwords may
1.173 + be needed for the -L -h all command and the -M command.
1.174 +
1.175 + Perhaps RC4 should not be supported as a key type. Use of these keys as
1.176 + fixed keys is exceedingly dangerous.
1.177 +
1.178 + The handling of multiple keys with the same nickname should be more
1.179 + deterministic than 'the first one'
1.180 +
1.181 + There is no way to specify, or display the operation flags of a key. The
1.182 + operation flags are not copied with the -M option as they should be.
1.183 +
1.184 + There is no way to change the attributes of a key (nickname, id, operation
1.185 + flags).
