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