1 2NAME 3 symkeyutil - manage fixed keys in the database 4 5SYNOPSIS 6 symkeyutil -H 7 symkeyutil -L [std_opts] [-r] 8 symkeyutil -K [-n name] -t type [-s size] [-i id |-j id_file] [std_opts] 9 symkeyutil -D <[-n name | -i id | -j id_file> [std_opts] 10 symkeyutil -I [-n name] [-t type] [-i id | -j id_file] -k data_file [std_opts] 11 symkeyutil -E <-nname | -i id | -j id_file> [-t type] -k data_file [-r] [std_opts] 12 symkeyutil -U [-n name] [-t type] [-i id | -j id_file] -k data_file <wrap_opts> [std_opts] 13 symkeyutil -W <-n name | -i id | -j id_file> [-t type] -k data_file [-r] <wrap_opts> [std_opts] 14 symkeyutil -M <-n name | -i id | -j id_file> -g target_token [std_opts] 15 std_opts -> [-d certdir] [-P dbprefix] [-p password] [-f passwordFile] [-h token] 16 wrap_opts -> <-w wrap_name | -x wrap_id | -y id_file> 17 18DESCRIPTION 19 20 NSS can store fixed keys as well as asymetric keys in the database. The 21 symkeyutil command can be used to manage these keys. 22 23 As with certutil, symkeyutil takes two types of arguments, commands and 24 options. Most commands fall into one of two catagories: commands which 25 create keys and commands which extract or destroy keys. 26 27 Exceptions to these catagories are listed first: 28 29 -H takes no additional options. It lists a more detailed help message. 30 -L takes the standard set of options. It lists all the keys in the 31 specified token (NSS Internal DB Token is the default). Only the 32 -L option accepts the all option for tokens to list all the fixed 33 keys. 34 35 Key Creation commands: 36 For these commands, the key type (-t) option is always required. 37 In addition, the -s option may be required for certain key types. 38 The standard set of options may be specified. 39 40 -K Create a new key using the token key gen function. 41 -I Import a new key from the raw data specified in the data file, 42 specified with the -k options (required). This command may fail on 43 some tokens that don't support direct import of key material. 44 -U Unwrap a new key from an encrypted data file specified with the -k 45 option. The -w, -x, or -y option specifies the unwrapping key. 46 The unwrapping algorithm is selected based on the type of the 47 unwrapping key. 48 49 Key extraction/destruction options: 50 For these keys, one and only of of the -n, -i, or -j options must be 51 specified. If more than one key matches the -n option, the 'first' key 52 matching will be used. The standard set of options may be specified. 53 54 -D Delete the key specified by the -n, -i, or -j options. 55 -E Export the key specified by the -n, -i, or -j options and store the 56 contents to a file specified by the -k file (required). 57 This command will seldom work on any token since most keys are 58 protected from export. 59 -W Wrap the key specified by the -n, -i, or -j options and store the 60 encrypted contents to a file specified by the -k file (required). 61 The -w, -x, or -y option specifies the key used to wrap the 62 target key. 63 -M Move the key specified by the -n, -i, or -j options to the token 64 specified by the -g option (required). The new key will have the 65 same attributes as the source key. 66 67OPTIONS 68 69 Standard options are those options that may be used by any command, and 70 whose meaning is the same for all commands. 71 72 -h token Specify the token which the command will operate on. 73 If -h is not specified the internal token is presumed. In 74 addition the special value 'all' may be used to specify 75 that all tokens should be used. This is only valid for 76 the '-L' command. 77 -d certdir Specify the location of the NSS databases. The default 78 value is platform dependent. 79 -P dbprefix Specify the prefix for the NSS database. The default value 80 is NULL. 81 -p password Specify the password for the token. On the command line. 82 The -p and -f options are mutually exclusive. If 83 neither option is specified, the password would be 84 prompted from the user. 85 -f passwordFile Specify a file that contains the password for the token. 86 This option is mutually exclusive to the -p option. 87 88 In addition to the standard options are the following command specific 89 options are. 90 91 -r Opens the NSS databases Read/Write. By default the -L, 92 -E, and -W commands open the database read only. Other 93 commands automatically opens the databases Read/Write and 94 igore this option if it is specified. 95 96 -n name Specifies the nickname for the key. 97 98 For the -K, -I, or -U options, name is the name for 99 the new key. If -n is not specified, no name is 100 assumed. There is not check for duplicate names. 101 102 For the -D, -E, -W, or -M, the name specifies the key to 103 operate on. In this case one andy only one of the -n, -i 104 or -j options should be specifed. It is possible that 105 the -n options specifies and ambiguous key. In that case 106 the 'first' valid key is used. 107 108 For the -M option, the nickname for the new key is copied 109 from it's original key, even if the original key is 110 specified using -i or -j. 111 112 -i key id 113 -j key id file These options are equivalent and mutually exclusive. 114 They specify the key id for the file. The -i option 115 specifies the key id on the command line using a hex 116 string. The -j specifies a file to read the raw key 117 id from. 118 119 For the -K, -I, or -U options, key id is the key id for 120 the new key. If -i or -j is not specified, no key id 121 is assumed. Some tokens may generate their own unique 122 id for the key in this case (but it is not guarrenteed). 123 124 For the -D, -E, -W, or -M, the key id specifies the key to 125 operate on. In this case one andy only one of the -n, -i 126 or -j options should be specifed. 127 128 -t type Specifies the key Type for the new key. This option is 129 required for the -K, -I, and -U commands. Valid values 130 are: 131 generic, rc2, rc4, des, des2, des3, cast, cast3, 132 cast5, cast128, rc5, idea, skipjack, baton, juniper, 133 cdmf, aes, camellia 134 135 Not all tokens support all key types. The generic key 136 type is usually used in MACing and key derivation 137 algorithms. Neither generic nor rc4 keys may be used 138 to wrap other keys. Fixed rc4 keys are dangerous since 139 multiple use of the same stream cipher key to encrypted 140 different data can compromise all data encrypted with 141 that key. 142 143 -s size Specifies the key size. For most situations the key size 144 is already known and need not be specified. For some 145 algorithms, however, it is necessary to specify the key 146 size when generation or unwrapping the key. 147 148 -k key file Specifies the name of a file that contains key data to 149 import or unwrap (-I or -U), or the location to store 150 key data or encrypted key data (-E or -W). 151 152 -g target token Specifies the target token when moving a key (-M). This 153 option is required for the -M command. It is invalid for 154 all other commands. 155 156 157 158 -w wrap name 159 -x wrap key id 160 -y wrap key id file Specifies the wrapping key used int the -U and -W 161 command. Exactly one of these must be specified for the 162 -U or -W commands. Same semantics as the -n, -i, and -j 163 options above. 164 165BUGS 166 167 There is no way display the key id of a key. 168 169 The -p and -f options only specifies one password. Multiple passwords may 170 be needed for the -L -h all command and the -M command. 171 172 Perhaps RC4 should not be supported as a key type. Use of these keys as 173 fixed keys is exceedingly dangerous. 174 175 The handling of multiple keys with the same nickname should be more 176 deterministic than 'the first one' 177 178 There is no way to specify, or display the operation flags of a key. The 179 operation flags are not copied with the -M option as they should be. 180 181 There is no way to change the attributes of a key (nickname, id, operation 182 flags). 183