doc/specify-user-id.texi

   1 @c Include file to allow for different placements in man pages and the manual
   2
   3 There are different ways to specify a user ID to GnuPG.  Some of them
   4 are only valid for @command{gpg} others are only good for
   5 @command{gpgsm}.  Here is the entire list of ways to specify a key:
   6
   7 @itemize @bullet
   8
   9 @item By key Id.
  10 This format is deduced from the length of the string and its content or
  11 @code{0x} prefix. The key Id of an X.509 certificate are the low 64 bits
  12 of its SHA-1 fingerprint.  The use of key Ids is just a shortcut, for
  13 all automated processing the fingerprint should be used.
  14
  15 When using @command{gpg} an exclamation mark (!) may be appended to
  16 force using the specified primary or secondary key and not to try and
  17 calculate which primary or secondary key to use.
  18
  19 The last four lines of the example give the key ID in their long form as
  20 internally used by the OpenPGP protocol. You can see the long key ID
  21 using the option @option{--with-colons}.
  22
  23 @cartouche
  24 @example
  25 234567C4
  26 0F34E556E
  27 01347A56A
  28 0xAB123456
  29
  30 234AABBCC34567C4
  31 0F323456784E56EAB
  32 01AB3FED1347A5612
  33 0x234AABBCC34567C4
  34 @end example
  35 @end cartouche
  36
  37
  38
  39 @item By fingerprint.
  40 This format is deduced from the length of the string and its content or
  41 the @code{0x} prefix.  Note, that only the 20 byte version fingerprint
  42 is available with @command{gpgsm} (i.e. the SHA-1 hash of the
  43 certificate).
  44
  45 When using @command{gpg} an exclamation mark (!) may be appended to
  46 force using the specified primary or secondary key and not to try and
  47 calculate which primary or secondary key to use.
  48
  49 The best way to specify a key Id is by using the fingerprint.  This
  50 avoids any ambiguities in case that there are duplicated key IDs.
  51
  52 @cartouche
  53 @example
  54 1234343434343434C434343434343434
  55 123434343434343C3434343434343734349A3434
  56 0E12343434343434343434EAB3484343434343434
  57 0xE12343434343434343434EAB3484343434343434
  58 @end example
  59 @end cartouche
  60
  61 @noindent
  62 (@command{gpgsm} also accepts colons between each pair of hexadecimal
  63 digits because this is the de-facto standard on how to present X.509
  64 fingerprints.)
  65
  66 @item By exact match on OpenPGP user ID.
  67 This is denoted by a leading equal sign. It does not make sense for
  68 X.509 certificates.
  69
  70 @cartouche
  71 @example
  72 =Heinrich Heine <heinrichh@@uni-duesseldorf.de>
  73 @end example
  74 @end cartouche
  75
  76 @item By exact match on an email address.
  77 This is indicated by enclosing the email address in the usual way
  78 with left and right angles.
  79
  80 @cartouche
  81 @example
  82 <heinrichh@@uni-duesseldorf.de>
  83 @end example
  84 @end cartouche
  85
  86
  87 @item By word match.
  88 All words must match exactly (not case sensitive) but can appear in any
  89 order in the user ID or a subjects name.  Words are any sequences of
  90 letters, digits, the underscore and all characters with bit 7 set.
  91
  92 @cartouche
  93 @example
  94 +Heinrich Heine duesseldorf
  95 @end example
  96 @end cartouche
  97
  98 @item By exact match on the subject's DN.
  99 This is indicated by a leading slash, directly followed by the RFC-2253
 100 encoded DN of the subject.  Note that you can't use the string printed
 101 by "gpgsm --list-keys" because that one as been reordered and modified
 102 for better readability; use --with-colons to print the raw (but standard
 103 escaped) RFC-2253 string
 104
 105 @cartouche
 106 @example
 107 /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
 108 @end example
 109 @end cartouche
 110
 111 @item By exact match on the issuer's DN.
 112 This is indicated by a leading hash mark, directly followed by a slash
 113 and then directly followed by the rfc2253 encoded DN of the issuer.
 114 This should return the Root cert of the issuer.  See note above.
 115
 116 @cartouche
 117 @example
 118 #/CN=Root Cert,O=Poets,L=Paris,C=FR
 119 @end example
 120 @end cartouche
 121
 122
 123 @item By exact match on serial number and issuer's DN.
 124 This is indicated by a hash mark, followed by the hexadecimal
 125 representation of the serial number, then followed by a slash and the
 126 RFC-2253 encoded DN of the issuer. See note above.
 127
 128 @cartouche
 129 @example
 130 #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
 131 @end example
 132 @end cartouche
 133
 134 @item By keygrip
 135 This is indicated by an ampersand followed by the 40 hex digits of a
 136 keygrip.  @command{gpgsm} prints the keygrip when using the command
 137 @option{--dump-cert}.  It does not yet work for OpenPGP keys.
 138
 139 @cartouche
 140 @example
 141 &D75F22C3F86E355877348498CDC92BD21010A480
 142 @end example
 143 @end cartouche
 144
 145
 146 @item By substring match.
 147 This is the default mode but applications may want to explicitly
 148 indicate this by putting the asterisk in front.  Match is not case
 149 sensitive.
 150
 151 @cartouche
 152 @example
 153 Heine
 154 *Heine
 155 @end example
 156 @end cartouche
 157
 158 @end itemize
 159
 160
 161 Please note that we have reused the hash mark identifier which was used
 162 in old GnuPG versions to indicate the so called local-id.  It is not
 163 anymore used and there should be no conflict when used with X.509 stuff.
 164
 165 Using the RFC-2253 format of DNs has the drawback that it is not
 166 possible to map them back to the original encoding, however we don't
 167 have to do this because our key database stores this encoding as meta
 168 data.
 169
 170
 171