diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 16:14:06 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 16:14:06 +0000 |
commit | eee068778cb28ecf3c14e1bf843a95547d72c42d (patch) | |
tree | 0e07b30ddc5ea579d682d5dbe57998200d1c9ab7 /doc/specify-user-id.texi | |
parent | Initial commit. (diff) | |
download | gnupg2-eee068778cb28ecf3c14e1bf843a95547d72c42d.tar.xz gnupg2-eee068778cb28ecf3c14e1bf843a95547d72c42d.zip |
Adding upstream version 2.2.40.upstream/2.2.40upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | doc/specify-user-id.texi | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/doc/specify-user-id.texi b/doc/specify-user-id.texi new file mode 100644 index 0000000..64e354b --- /dev/null +++ b/doc/specify-user-id.texi @@ -0,0 +1,173 @@ +@c Include file to allow for different placements in man pages and the manual + +There are different ways to specify a user ID to GnuPG. Some of them +are only valid for @command{gpg} others are only good for +@command{gpgsm}. Here is the entire list of ways to specify a key: + +@itemize @bullet + +@item By key Id. +This format is deduced from the length of the string and its content or +@code{0x} prefix. The key Id of an X.509 certificate are the low 64 bits +of its SHA-1 fingerprint. The use of key Ids is just a shortcut, for +all automated processing the fingerprint should be used. + +When using @command{gpg} an exclamation mark (!) may be appended to +force using the specified primary or secondary key and not to try and +calculate which primary or secondary key to use. + +The last four lines of the example give the key ID in their long form as +internally used by the OpenPGP protocol. You can see the long key ID +using the option @option{--with-colons}. + +@cartouche +@example +234567C4 +0F34E556E +01347A56A +0xAB123456 + +234AABBCC34567C4 +0F323456784E56EAB +01AB3FED1347A5612 +0x234AABBCC34567C4 +@end example +@end cartouche + + + +@item By fingerprint. +This format is deduced from the length of the string and its content or +the @code{0x} prefix. Note, that only the 20 byte version fingerprint +is available with @command{gpgsm} (i.e. the SHA-1 hash of the +certificate). + +When using @command{gpg} an exclamation mark (!) may be appended to +force using the specified primary or secondary key and not to try and +calculate which primary or secondary key to use. + +The best way to specify a key Id is by using the fingerprint. This +avoids any ambiguities in case that there are duplicated key IDs. + +@cartouche +@example +1234343434343434C434343434343434 +123434343434343C3434343434343734349A3434 +0E12343434343434343434EAB3484343434343434 +0xE12343434343434343434EAB3484343434343434 +@end example +@end cartouche + +@noindent +@command{gpgsm} also accepts colons between each pair of hexadecimal +digits because this is the de-facto standard on how to present X.509 +fingerprints. @command{gpg} also allows the use of the space +separated SHA-1 fingerprint as printed by the key listing commands. + +@item By exact match on OpenPGP user ID. +This is denoted by a leading equal sign. It does not make sense for +X.509 certificates. + +@cartouche +@example +=Heinrich Heine <heinrichh@@uni-duesseldorf.de> +@end example +@end cartouche + +@item By exact match on an email address. +This is indicated by enclosing the email address in the usual way +with left and right angles. + +@cartouche +@example +<heinrichh@@uni-duesseldorf.de> +@end example +@end cartouche + + +@item By partial match on an email address. +This is indicated by prefixing the search string with an @code{@@}. +This uses a substring search but considers only the mail address +(i.e. inside the angle brackets). + +@cartouche +@example +@@heinrichh +@end example +@end cartouche + +@item By exact match on the subject's DN. +This is indicated by a leading slash, directly followed by the RFC-2253 +encoded DN of the subject. Note that you can't use the string printed +by @code{gpgsm --list-keys} because that one has been reordered and modified +for better readability; use @option{--with-colons} to print the raw +(but standard escaped) RFC-2253 string. + +@cartouche +@example +/CN=Heinrich Heine,O=Poets,L=Paris,C=FR +@end example +@end cartouche + +@item By exact match on the issuer's DN. +This is indicated by a leading hash mark, directly followed by a slash +and then directly followed by the RFC-2253 encoded DN of the issuer. +This should return the Root cert of the issuer. See note above. + +@cartouche +@example +#/CN=Root Cert,O=Poets,L=Paris,C=FR +@end example +@end cartouche + + +@item By exact match on serial number and issuer's DN. +This is indicated by a hash mark, followed by the hexadecimal +representation of the serial number, then followed by a slash and the +RFC-2253 encoded DN of the issuer. See note above. + +@cartouche +@example +#4F03/CN=Root Cert,O=Poets,L=Paris,C=FR +@end example +@end cartouche + +@item By keygrip. +This is indicated by an ampersand followed by the 40 hex digits of a +keygrip. @command{gpgsm} prints the keygrip when using the command +@option{--dump-cert}. + +@cartouche +@example +&D75F22C3F86E355877348498CDC92BD21010A480 +@end example +@end cartouche + + +@item By substring match. +This is the default mode but applications may want to explicitly +indicate this by putting the asterisk in front. Match is not case +sensitive. + +@cartouche +@example +Heine +*Heine +@end example +@end cartouche + +@item . and + prefixes +These prefixes are reserved for looking up mails anchored at the end +and for a word search mode. They are not yet implemented and using +them is undefined. + +@end itemize + +Please note that we have reused the hash mark identifier which was used +in old GnuPG versions to indicate the so called local-id. It is not +anymore used and there should be no conflict when used with X.509 stuff. + +Using the RFC-2253 format of DNs has the drawback that it is not +possible to map them back to the original encoding, however we don't +have to do this because our key database stores this encoding as meta +data. |