doc: Fix documentation.
[gnupg.git] / 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.  @command{gpg} also allows the use of the space
65 separated SHA-1 fingerprint as printed by the key listing commands.
66
67 @item By exact match on OpenPGP user ID.
68 This is denoted by a leading equal sign. It does not make sense for
69 X.509 certificates.
70
71 @cartouche
72 @example
73 =Heinrich Heine <heinrichh@@uni-duesseldorf.de>
74 @end example
75 @end cartouche
76
77 @item By exact match on an email address.
78 This is indicated by enclosing the email address in the usual way
79 with left and right angles.
80
81 @cartouche
82 @example
83 <heinrichh@@uni-duesseldorf.de>
84 @end example
85 @end cartouche
86
87
88 @item By partial match on an email address.
89 This is indicated by prefixing the search string with an @code{@@}.
90 This uses a substring search but considers only the mail address
91 (i.e. inside the angle brackets).
92
93 @cartouche
94 @example
95 @@heinrichh
96 @end example
97 @end cartouche
98
99 @item By exact match on the subject's DN.
100 This is indicated by a leading slash, directly followed by the RFC-2253
101 encoded DN of the subject.  Note that you can't use the string printed
102 by @code{gpgsm --list-keys} because that one has been reordered and modified
103 for better readability; use @option{--with-colons} to print the raw
104 (but standard escaped) RFC-2253 string.
105
106 @cartouche
107 @example
108 /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
109 @end example
110 @end cartouche
111
112 @item By exact match on the issuer's DN.
113 This is indicated by a leading hash mark, directly followed by a slash
114 and then directly followed by the RFC-2253 encoded DN of the issuer.
115 This should return the Root cert of the issuer.  See note above.
116
117 @cartouche
118 @example
119 #/CN=Root Cert,O=Poets,L=Paris,C=FR
120 @end example
121 @end cartouche
122
123
124 @item By exact match on serial number and issuer's DN.
125 This is indicated by a hash mark, followed by the hexadecimal
126 representation of the serial number, then followed by a slash and the
127 RFC-2253 encoded DN of the issuer. See note above.
128
129 @cartouche
130 @example
131 #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
132 @end example
133 @end cartouche
134
135 @item By keygrip.
136 This is indicated by an ampersand followed by the 40 hex digits of a
137 keygrip.  @command{gpgsm} prints the keygrip when using the command
138 @option{--dump-cert}.  It does not yet work for OpenPGP keys.
139
140 @cartouche
141 @example
142 &D75F22C3F86E355877348498CDC92BD21010A480
143 @end example
144 @end cartouche
145
146
147 @item By substring match.
148 This is the default mode but applications may want to explicitly
149 indicate this by putting the asterisk in front.  Match is not case
150 sensitive.
151
152 @cartouche
153 @example
154 Heine
155 *Heine
156 @end example
157 @end cartouche
158
159 @item . and + prefixes
160 These prefixes are reserved for looking up mails anchored at the end
161 and for a word search mode.  They are not yet implemented and using
162 them is undefined.
163
164 @end itemize
165
166 Please note that we have reused the hash mark identifier which was used
167 in old GnuPG versions to indicate the so called local-id.  It is not
168 anymore used and there should be no conflict when used with X.509 stuff.
169
170 Using the RFC-2253 format of DNs has the drawback that it is not
171 possible to map them back to the original encoding, however we don't
172 have to do this because our key database stores this encoding as meta
173 data.
174
175
176