mozilla/security/nss/cmd/symkeyutil/symkey.man

   1
   2 NAME
   3     symkeyutil - manage fixed keys in the database
   4
   5 SYNOPSIS
   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
  18 DESCRIPTION
  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
  67 OPTIONS
  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
 165 BUGS
 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).