diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/DETAILS | 12 | ||||
| -rw-r--r-- | doc/HACKING | 6 | ||||
| -rw-r--r-- | doc/Makefile.am | 7 | ||||
| -rw-r--r-- | doc/Notes | 6 | ||||
| -rw-r--r-- | doc/dirmngr.texi | 2 | ||||
| -rw-r--r-- | doc/faq.org | 2 | ||||
| -rw-r--r-- | doc/gnupg.texi | 12 | ||||
| -rw-r--r-- | doc/gpg-agent.texi | 30 | ||||
| -rw-r--r-- | doc/gpg-card.texi | 517 | ||||
| -rw-r--r-- | doc/gpg.texi | 65 | ||||
| -rw-r--r-- | doc/gpgv.texi | 15 | ||||
| -rw-r--r-- | doc/specify-user-id.texi | 5 | ||||
| -rw-r--r-- | doc/tools.texi | 15 | ||||
| -rw-r--r-- | doc/wks.texi | 96 | ||||
| -rw-r--r-- | doc/yat2m.c | 6 |
15 files changed, 693 insertions, 103 deletions
diff --git a/doc/DETAILS b/doc/DETAILS index eb6d7dd4b..74a63ef00 100644 --- a/doc/DETAILS +++ b/doc/DETAILS @@ -59,7 +59,7 @@ described here. - uat :: User attribute (same as user id except for field 10). - sig :: Signature - rev :: Revocation signature - - rvs :: Recocation signature (standalone) [since 2.2.9] + - rvs :: Revocation signature (standalone) [since 2.2.9] - fpr :: Fingerprint (fingerprint is in field 10) - pkd :: Public key data [*] - grp :: Keygrip @@ -126,7 +126,7 @@ described here. *** Field 4 - Public key algorithm The values here are those from the OpenPGP specs or if they are - greather than 255 the algorithm ids as used by Libgcrypt. + greater than 255 the algorithm ids as used by Libgcrypt. *** Field 5 - KeyID @@ -544,7 +544,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB: *** DECRYPTION_KEY <fpr> <fpr2> <otrust> This line is emitted when a public key decryption succeeded in providing a session key. <fpr> is the hexified fingerprint of the - actual key used for descryption. <fpr2> is the fingerprint of the + actual key used for decryption. <fpr2> is the fingerprint of the primary key. <otrust> is the letter with the ownertrust; this is in general a 'u' which stands for ultimately trusted. *** DECRYPTION_INFO <mdc_method> <sym_algo> [<aead_algo>] @@ -700,7 +700,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB: - 0 :: No specific reason given - 1 :: Not Found - - 2 :: Ambigious specification + - 2 :: Ambiguous specification - 3 :: Wrong key usage - 4 :: Key revoked - 5 :: Key expired @@ -1016,7 +1016,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB: - 2 :: bad PIN *** SC_OP_SUCCESS - A smart card operaion succeeded. This status is only printed for + A smart card operation succeeded. This status is only printed for certain operation and is mostly useful to check whether a PIN change really worked. @@ -1073,7 +1073,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB: Deleting a key failed. Reason codes are: - 1 :: No such key - 2 :: Must delete secret key first - - 3 :: Ambigious specification + - 3 :: Ambiguous specification - 4 :: Key is stored on a smartcard. *** PROGRESS <what> <char> <cur> <total> [<units>] diff --git a/doc/HACKING b/doc/HACKING index 17c58269b..4781bf62c 100644 --- a/doc/HACKING +++ b/doc/HACKING @@ -150,7 +150,7 @@ Note that such a comment will be removed if the git commit option if ( 42 == foo ) #+end_src this is harder to read and modern compilers are pretty good in - detecing accidential assignments. It is also suggested not to + detecing accidental assignments. It is also suggested not to compare to 0 or NULL but to test the value direct or with a '!'; this makes it easier to see that a boolean test is done. - We use our own printf style functions like =es_printf=, and @@ -342,7 +342,7 @@ Note that such a comment will be removed if the git commit option - g10/main.h :: Prototypes and some constants - g10/mainproc.c :: Message processing - g10/armor.c :: Ascii armor filter - - g10/mdfilter.c :: Filter to calculate hashs + - g10/mdfilter.c :: Filter to calculate hashes - g10/textfilter.c :: Filter to handle CR/LF and trailing white space - g10/cipher.c :: En-/Decryption filter - g10/misc.c :: Utility functions @@ -395,7 +395,7 @@ The *secure versions allocate memory in the secure memory. That is, swapping out of this memory is avoided and is gets overwritten on free. Use this for passphrases, session keys and other sensitive material. This memory set aside for secure memory is linited to a few -k. In general the function don't print a memeory message and +k. In general the function don't print a memory message and terminate the process if there is not enough memory available. The "try" versions of the functions return NULL instead. diff --git a/doc/Makefile.am b/doc/Makefile.am index cb69cd993..0720dd366 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -69,7 +69,7 @@ nobase_dist_doc_DATA = FAQ DETAILS HACKING DCO TRANSLATE OpenPGP KEYSERVER \ gnupg_TEXINFOS = \ gpg.texi gpgsm.texi gpg-agent.texi scdaemon.texi instguide.texi \ tools.texi debugging.texi glossary.texi contrib.texi gpl.texi \ - sysnotes.texi dirmngr.texi wks.texi \ + sysnotes.texi dirmngr.texi wks.texi gpg-card.texi \ gnupg-module-overview.svg \ gnupg-card-architecture.fig \ howtos.texi howto-create-a-server-cert.texi @@ -89,12 +89,13 @@ YAT2M_OPTIONS = -I $(srcdir) \ --release "GnuPG @PACKAGE_VERSION@" --source "GNU Privacy Guard 2.2" myman_sources = gnupg7.texi gpg.texi gpgsm.texi gpg-agent.texi \ - dirmngr.texi scdaemon.texi tools.texi wks.texi + dirmngr.texi scdaemon.texi tools.texi wks.texi \ + gpg-card.texi myman_pages = gpgsm.1 gpg-agent.1 dirmngr.8 scdaemon.1 \ watchgnupg.1 gpgconf.1 addgnupghome.8 gpg-preset-passphrase.1 \ gpg-connect-agent.1 gpgparsemail.1 symcryptrun.1 gpgtar.1 \ applygnupgdefaults.8 gpg-wks-client.1 gpg-wks-server.1 \ - dirmngr-client.1 + dirmngr-client.1 gpg-card.1 if USE_GPG2_HACK myman_pages += gpg2.1 gpgv2.1 else @@ -1,5 +1,5 @@ -Add an infor page for watchgnupg. +Add an info page for watchgnupg. > * How to mark a CA certificate as trusted. @@ -57,7 +57,7 @@ or In general you should first import the root certificates and then down to the end user certificate. You may put all into one file and gpgsm -will do the right thing in this case independend of the order. +will do the right thing in this case independent of the order. While verifying a signature, all included certificates are automagically imported. @@ -82,7 +82,7 @@ you get an output like: uid:::::::::CN=Werner Koch,OU=test,O=g10 Code,C=de:: uid:::::::::<[email protected]>:: -This should be familar to advanced gpg-users; see doc/DETAILS in gpg +This should be familiar to advanced gpg-users; see doc/DETAILS in gpg 1.3 (CVS HEAD) for a description of the records. The value in the "grp" tagged record is the so called keygrip and you should find a file ~/.gnupg/private-keys-v1.d/C92DB9CFD588ADE846BE3AC4E7A2E1B11A4A2ADB.key diff --git a/doc/dirmngr.texi b/doc/dirmngr.texi index 76be5286c..f5910a884 100644 --- a/doc/dirmngr.texi +++ b/doc/dirmngr.texi @@ -1096,7 +1096,7 @@ as a binary blob. @c In the end the same fucntionality is used, albeit hidden by a couple @c of indirection and argument and result code mangling. It furthere @c ingetrages OCSP checking depending on options are the way it is -@c called. GPGSM still uses this command but might eventuall switch over +@c called. GPGSM still uses this command but might eventually switch over @c to CHECKCRL and CHECKOCSP so that ISVALID can be retired. @c @c diff --git a/doc/faq.org b/doc/faq.org index ddbeafaf8..2f873e600 100644 --- a/doc/faq.org +++ b/doc/faq.org @@ -1096,7 +1096,7 @@ update this FAQ in the next month. See the section "Changes" for recent updates As of 1.0.3, keys generated with gpg are created with preferences to TWOFISH (and AES since 1.0.4) and that also means that they have the capability to use the new MDC encryption method. This will go into - OpenPGP soon, and is also suppoted by PGP 7. This new method avoids + OpenPGP soon, and is also supported by PGP 7. This new method avoids a (not so new) attack on all email encryption systems. This in turn means that pre-1.0.3 gpg binaries have problems with diff --git a/doc/gnupg.texi b/doc/gnupg.texi index 336414870..78d4669da 100644 --- a/doc/gnupg.texi +++ b/doc/gnupg.texi @@ -142,15 +142,16 @@ the administration and the architecture. * Specify a User ID:: How to Specify a User Id. * Trust Values:: How GnuPG displays trust values. -* Helper Tools:: Description of small helper tools -* Web Key Service:: Tools for the Web Key Service +* Smart Card Tool:: Tool to administrate smart cards. +* Helper Tools:: Description of small helper tools. +* Web Key Service:: Tools for the Web Key Service. * Howtos:: How to do certain things. * System Notes:: Notes pertaining to certain OSes. -* Debugging:: How to solve problems +* Debugging:: How to solve problems. * Copying:: GNU General Public License says - how you can copy and share GnuPG + how you can copy and share GnuPG. * Contributors:: People who have contributed to GnuPG. * Glossary:: Short description of terms used. @@ -186,6 +187,7 @@ the administration and the architecture. @cindex trust values @include trust-values.texi +@include gpg-card.texi @include tools.texi @include wks.texi @@ -237,5 +239,3 @@ the administration and the architecture. @bye - - diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi index bcce03329..d518c246b 100644 --- a/doc/gpg-agent.texi +++ b/doc/gpg-agent.texi @@ -585,16 +585,19 @@ local gpg-agent and use its private keys. This enables decrypting or signing data on a remote machine without exposing the private keys to the remote machine. -@anchor{option --enable-extended-key-format} @item --enable-extended-key-format +@itemx --disable-extended-key-format @opindex enable-extended-key-format -This option creates keys in the extended private key format. Changing -the passphrase of a key will also convert the key to that new format. -Using this option makes the private keys unreadable for gpg-agent -versions before 2.1.12. The advantage of the extended private key -format is that it is text based and can carry additional meta data. -Note that this option also changes the key protection format to use -OCB mode. +@opindex disable-extended-key-format +Since version 2.3 keys are created in the extended private key format. +Changing the passphrase of a key will also convert the key to that new +format. This new key format is supported since GnuPG version 2.1.12 +and thus there should be no need to disable it. The disable option +allows to revert to the old behavior for new keys; be aware that keys +are never migrated back to the old format. However if the enable +option has been used the disable option won't have an effect. The +advantage of the extended private key format is that it is text based +and can carry additional meta data. @anchor{option --enable-ssh-support} @item --enable-ssh-support @@ -669,12 +672,19 @@ For an heavy loaded gpg-agent with many concurrent connection this option avoids sign or decrypt errors due to out of secure memory error returns. +@item --s2k-calibration @var{milliseconds} +@opindex s2k-calibration +Change the default calibration time to @var{milliseconds}. The given +value is capped at 60 seconds; a value of 0 resets to the compiled-in +default. This option is re-read on a SIGHUP (or @code{gpgconf +--reload gpg-agent}) and the S2K count is then re-calibrated. + @item --s2k-count @var{n} @opindex s2k-count Specify the iteration count used to protect the passphrase. This option can be used to override the auto-calibration done by default. -The auto-calibration computes a count which requires 100ms to mangle -a given passphrase. +The auto-calibration computes a count which requires by default 100ms +to mangle a given passphrase. See also @option{--s2k-calibration}. To view the actually used iteration count and the milliseconds required for an S2K operation use: diff --git a/doc/gpg-card.texi b/doc/gpg-card.texi new file mode 100644 index 000000000..aa49f81e7 --- /dev/null +++ b/doc/gpg-card.texi @@ -0,0 +1,517 @@ +@c card-tool.texi - man page for gpg-card-tool +@c Copyright (C) 2019 g10 Code GmbH +@c This is part of the GnuPG manual. +@c For copying conditions, see the file GnuPG.texi. + +@include defs.inc + +@node Smart Card Tool +@chapter Smart Card Tool + +GnuPG comes with tool to administrate smart cards and USB tokens. This +tool is an extension of the @option{--edit-key} command available with +@command{gpg}. + +@menu +* gpg-card:: Administrate smart cards. +@end menu + +@c +@c GPG-CARD-TOOL +@c +@manpage gpg-card.1 +@node gpg-card +@section Administrate smart cards. +@ifset manverb +.B gpg-card +\- Administrate Smart Cards +@end ifset + +@mansect synopsis +@ifset manverb +.B gpg-card +.RI [ options ] +.br +.B gpg-card +.RI [ options ] +.I command +.RI { +.B -- +.I command +.RI } +@end ifset + +@mansect description +The @command{gpg-card} is used to administrate smart cards and USB +tokens. It provides a superset of features from @command{gpg +--card-edit} an can be considered a frontend to @command{scdaemon} +which is a daemon started by @command{gpg-agent} to handle smart +cards. + +If @command{gpg-card} is invoked without commands an interactive +mode is used. + +If @command{gpg-card} is invoked with one or more commands the +same commands as available in the interactive mode are run from the +command line. These commands need to be delimited with a double-dash. +If a double-dash or a shell specific character is required as part of +a command the entire command needs to be put in quotes. If one of +those commands returns an error the remaining commands are mot anymore +run unless the command was prefixed with a single dash. + +A list of commands is available by using the command @code{help} and a +detailed description of each command is printed by using @code{help +COMMAND}. + +See the NOTES sections for instructions pertaining to specific cards +or card applications. + +@mansect options +@noindent +@command{gpg-card} understands these options: + +@table @gnupgtabopt + +@item --with-colons +@opindex with-colons +This option has currently no effect. + +@item --status-fd @var{n} +@opindex status-fd +Write special status strings to the file descriptor @var{n}. This +program returns only the status messages SUCCESS or FAILURE which are +helpful when the caller uses a double fork approach and can't easily +get the return code of the process. + +@item --verbose +@opindex verbose +Enable extra informational output. + +@item --quiet +@opindex quiet +Disable almost all informational output. + +@item --version +@opindex version +Print version of the program and exit. + +@item --help +@opindex help +Display a brief help page and exit. + +@item --no-autostart +@opindex no-autostart +Do not start the gpg-agent if it has not yet been started and its +service is required. This option is mostly useful on machines where +the connection to gpg-agent has been redirected to another machines. + +@item --agent-program @var{file} +@opindex agent-program +Specify the agent program to be started if none is running. The +default value is determined by running @command{gpgconf} with the +option @option{--list-dirs}. + +@item --gpg-program @var{file} +@opindex gpg-program +Specify a non-default gpg binary to be used by certain commands. + +@item --gpgsm-program @var{file} +@opindex gpgsm-program +Specify a non-default gpgsm binary to be used by certain commands. + +@end table + +@mansect notes (OpenPGP) +The support for OpenPGP cards in @command{gpg-card} is not yet +complete. For missing features, please continue to use @code{gpg +--card-edit}. + +@mansect notes (PIV) +@noindent +GnuPG has support for PIV cards (``Personal Identity Verification'' +as specified by NIST Special Publication 800-73-4). This section +describes how to initialize (personalize) a fresh Yubikey token +featuring the PIV application (requires Yubikey-5). We assume that +the credentials have not yet been changed and thus are: +@table @asis +@item Authentication key +This is a 24 byte key described by the hex string +@code{010203040506070801020304050607080102030405060708}. +@item PIV Application PIN +This is the string @code{123456}. +@item PIN Unblocking Key +This is the string @code{12345678}. +@end table +See the example section on how to change these defaults. For +production use it is important to use secure values for them. Note that +the Authentication Key is not queried via the usual Pinentry dialog +but needs to be entered manually or read from a file. The use of a +dedicated machine to personalize tokens is strongly suggested. + +To see what is on the card, the command @code{list} can be given. We +will use the interactive mode in the following (the string +@emph{gpg/card>} is the prompt). An example output for a fresh card +is: + +@example +gpg/card> list +Reader ...........: 1050:0407:X:0 +Card type ........: yubikey +Card firmware ....: 5.1.2 +Serial number ....: D2760001240102010006090746250000 +Application type .: OpenPGP +Version ..........: 2.1 +[...] +@end example + +It can be seen by the ``Application type'' line that GnuPG selected the +OpenPGP application of the Yubikey. This is because GnuPG assigns the +highest priority to the OpenPGP application. To use the PIV +application of the Yubikey, the OpenPGP application needs to be +disabled: + +@example +gpg/card> yubikey disable all opgp +gpg/card> yubikey list +Application USB NFC +----------------------- +OTP yes yes +U2F yes yes +OPGP no no +PIV yes no +OATH yes yes +FIDO2 yes yes +gpg/card> reset +@end example + +The @code{reset} is required so that the GnuPG system rereads the +card. Note that disabled applications keep all their data and can at +any time be re-enabled (see @emph{help yubikey}). Now a @emph{list} +command shows this: + +@example +gpg/card> list +Reader ...........: 1050:0407:X:0 +Card type ........: yubikey +Card firmware ....: 5.1.2 +Serial number ....: FF020001008A77C1 +Application type .: PIV +Version ..........: 1.0 +Displayed s/n ....: yk-9074625 +PIN usage policy .: app-pin +PIN retry counter : - 3 - +PIV authentication: [none] + keyref .....: PIV.9A +Card authenticat. : [none] + keyref .....: PIV.9E +Digital signature : [none] + keyref .....: PIV.9C +Key management ...: [none] + keyref .....: PIV.9D +@end example + +Note that the ``Displayed s/sn'' is printed on the token and also +shown in Pinentry prompts asking for the PIN. The four standard key +slots are always shown, if other key slots are initialized they are +shown as well. The @emph{PIV authentication} key (internal reference +@emph{PIV.9A}) is used to authenticate the card and the card holder. +The use of the associated private key is protected by the Application +PIN which needs to be provided once and the key can the be used until +the card is reset or removed from the reader or USB port. GnuPG uses +this key with its @emph{Secure Shell} support. The @emph{Card +authentication} key (@emph{PIV.9E}) is also known as the CAK and used +to support physical access applications. The private key is not +protected by a PIN and can thus immediately be used. The @emph{Digital +signature} key (@emph{PIV.9C}) is used to digitally sign documents. +The use of the associated private key is protected by the Application +PIN which needs to be provided for each signing operation. The +@emph{Key management} key (@emph{PIV.9D}) is used for encryption. The +use of the associated private key is protected by the Application PIN +which needs to be provided only once so that decryption operations can +then be done until the card is reset or removed from the reader or USB +port. + +We now generate tree of the four keys. Note that GnuPG does currently +not use the the @emph{Card authentication} key but because it is +mandatory by the specs we create it anyway. Key generation requires +that we authenticate to the card. This can be done either on the +command line (which would reveal the key): + +@example +gpg/card> auth 010203040506070801020304050607080102030405060708 +@end example + +or by reading the key from a file. That file needs to consist of one +LF terminated line with the hex encoded key (as above): + +@example +gpg/card> auth < myauth.key +@end example + +As usual @samp{help auth} gives help for this command. An error +message is printed if a non-matching key is used. The authentication +is valid until a reset of the card or until the card is removed from +the reader or the USB port. Note that that in non-interactive mode +the @samp{<} needs to be quoted so that the shell does not interpret +it as a its own redirection symbol. + +@noindent +Here are the actual commands to generate the keys: + +@example +gpg/card> generate --algo=nistp384 PIV.9A +PIV card no. yk-9074625 detected +gpg/card> generate --algo=nistp256 PIV.9E +PIV card no. yk-9074625 detected +gpg/card> generate --algo=rsa2048 PIV.9C +PIV card no. yk-9074625 detected +@end example + +If a key has already been created for one of the slots an error will +be printed; to create a new key anyway the option @samp{--force} can be +used. Note that only the private and public keys have been created +but no certificates are stored in the key slots. In fact, GnuPG uses +its own non-standard method to store just the public key in place of +the the certificate. Other application will not be able to make use +these keys until @command{gpgsm} or another tool has been used to +create and store the respective certificates. Let us see what the +list command now shows: + +@example +gpg/card> list +Reader ...........: 1050:0407:X:0 +Card type ........: yubikey +Card firmware ....: 5.1.2 +Serial number ....: FF020001008A77C1 +Application type .: PIV +Version ..........: 1.0 +Displayed s/n ....: yk-9074625 +PIN usage policy .: app-pin +PIN retry counter : - 3 - +PIV authentication: 213D1825FDE0F8240CB4E4229F01AF90AC658C2E + keyref .....: PIV.9A (auth) + algorithm ..: nistp384 +Card authenticat. : 7A53E6CFFE7220A0E646B4632EE29E5A7104499C + keyref .....: PIV.9E (auth) + algorithm ..: nistp256 +Digital signature : 32A6C6FAFCB8421878608AAB452D5470DD3223ED + keyref .....: PIV.9C (sign,cert) + algorithm ..: rsa2048 +Key management ...: [none] + keyref .....: PIV.9D +@end example + +The primary information for each key is the @emph{keygrip}, a 40 byte +hex-string identifying the key. This keygrip is a unique identifier +for the specific parameters of a key. It is used by +@command{gpg-agent} and other parts of GnuPG to associate a private +key to its protocol specific certificate format (X.509, OpenPGP, or +SecureShell). Below the keygrip the key reference along with the key +usage capabilities are show. Finally the algorithm is printed in the +format used by @command {gpg}. At that point no other information is +shown because for these new keys gpg won't be able to find matching +certificates. + +Although we could have created the @emph{Key management} key also with +the generate command, we will create that key off-card so that a +backup exists. To accomplish this a key needs to be created with +either @command{gpg} or @command{gpgsm} or imported in one of these +tools. In our example we create a self-signed X.509 certificate (exit +the gpg-card tool, first): + +@example +$ gpgsm --gen-key -o encr.crt + (1) RSA + (2) Existing key + (3) Existing key from card +Your selection? 1 +What keysize do you want? (3072) 2048 +Requested keysize is 2048 bits +Possible actions for a RSA key: + (1) sign, encrypt + (2) sign + (3) encrypt +Your selection? 3 +Enter the X.509 subject name: CN=Encryption key for yk-9074625,O=example,C=DE +Enter email addresses (end with an empty line): +> otto@@example.net +> +Enter DNS names (optional; end with an empty line): +> +Enter URIs (optional; end with an empty line): +> +Create self-signed certificate? (y/N) y +These parameters are used: + Key-Type: RSA + Key-Length: 2048 + Key-Usage: encrypt + Serial: random + Name-DN: CN=Encryption key for yk-9074625,O=example,C=DE + Name-Email: otto@@example.net + +Proceed with creation? (y/N) +Now creating self-signed certificate. This may take a while ... +gpgsm: about to sign the certificate for key: &34798AAFE0A7565088101CC4AE31C5C8C74461CB +gpgsm: certificate created +Ready. +$ gpgsm --import encr.crt +gpgsm: certificate imported +gpgsm: total number processed: 1 +gpgsm: imported: 1 +@end example + +Note the last steps which imported the created certificate. If you +you instead created a certificate signing request (CSR) instead of a +self-signed certificate and sent this off to a CA you would do the +same import step with the certificate received from the CA. Take note +of the keygrip (prefixed with an ampersand) as shown during the +certificate creation or listed it again using @samp{gpgsm +--with-keygrip -k otto@@example.net}. Now to move the key and +certificate to the card start @command{gpg-card} again and enter: + +@example +gpg/card> writekey PIV.9D 34798AAFE0A7565088101CC4AE31C5C8C74461CB +gpg/card> writecert PIV.9D < encr.crt +@end example + +If you entered a passphrase to protect the private key, you will be +asked for it via the Pinentry prompt. On success the key and the +certificate has been written to the card and a @code{list} command +shows: + +@example +[...] +Key management ...: 34798AAFE0A7565088101CC4AE31C5C8C74461CB + keyref .....: PIV.9D (encr) + algorithm ..: rsa2048 + used for ...: X.509 + user id ..: CN=Encryption key for yk-9074625,O=example,C=DE + user id ..: <otto@@example.net> +@end example + +In case the same key (identified by the keygrip) has been used for +several certificates you will see several ``used for'' parts. With +this the encryption key is now fully functional and can be used to +decrypt messages encrypted to this certificate. @sc{Take care:} the +original key is still stored on-disk and should be moved to a backup +medium. This can simply be done by copying the file +@file{34798AAFE0A7565088101CC4AE31C5C8C74461CB.key} from the directory +@file{~/.gnupg/private-keys-v1.d/} to the backup medium and deleting +the file at its original place. + +The final example is to create a self-signed certificate for digital +signatures. Leave @command{gpg-card} using @code{quit} or by pressing +Control-D and use gpgsm: + +@example +$ gpgsm --learn +$ gpgsm --gen-key -o sign.crt +Please select what kind of key you want: + (1) RSA + (2) Existing key + (3) Existing key from card +Your selection? 3 +Serial number of the card: FF020001008A77C1 +Available keys: + (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384 + (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256 + (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048 + (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048 +Your selection? 3 +Possible actions for a RSA key: + (1) sign, encrypt + (2) sign + (3) encrypt +Your selection? 2 +Enter the X.509 subject name: CN=Signing key for yk-9074625,O=example,C=DE +Enter email addresses (end with an empty line): +> otto@@example.net +> +Enter DNS names (optional; end with an empty line): +> +Enter URIs (optional; end with an empty line): +> +Create self-signed certificate? (y/N) +These parameters are used: + Key-Type: card:PIV.9C + Key-Length: 1024 + Key-Usage: sign + Serial: random + Name-DN: CN=Signing key for yk-9074625,O=example,C=DE + Name-Email: otto@@example.net + +Proceed with creation? (y/N) y +Now creating self-signed certificate. This may take a while ... +gpgsm: about to sign the certificate for key: &32A6C6FAFCB8421878608AAB452D5470DD3223ED +gpgsm: certificate created +Ready. +$ gpgsm --import sign.crt +gpgsm: certificate imported +gpgsm: total number processed: 1 +gpgsm: imported: 1 +@end example + +The use of @samp{gpgsm --learn} is currently necessary so that +gpg-agent knows what keys are available on the card. The need for +this command will eventually be removed. The remaining commands are +similar to the creation of an on-disk key. However, here we select +the @samp{Digital signature} key. During the creation process you +will be asked for the Application PIN of the card. The final step is +to write the certificate to the card using @command{gpg-card}: + +@example +gpg/card> writecert PIV.9C < sign.crt +@end example + +By running list again we will see the fully initialized card: + +@example +Reader ...........: 1050:0407:X:0 +Card type ........: yubikey +Card firmware ....: 5.1.2 +Serial number ....: FF020001008A77C1 +Application type .: PIV +Version ..........: 1.0 +Displayed s/n ....: yk-9074625 +PIN usage policy .: app-pin +PIN retry counter : - [verified] - +PIV authentication: 213D1825FDE0F8240CB4E4229F01AF90AC658C2E + keyref .....: PIV.9A (auth) + algorithm ..: nistp384 +Card authenticat. : 7A53E6CFFE7220A0E646B4632EE29E5A7104499C + keyref .....: PIV.9E (auth) + algorithm ..: nistp256 +Digital signature : 32A6C6FAFCB8421878608AAB452D5470DD3223ED + keyref .....: PIV.9C (sign,cert) + algorithm ..: rsa2048 + used for ...: X.509 + user id ..: CN=Signing key for yk-9074625,O=example,C=DE + user id ..: <otto@@example.net> +Key management ...: 34798AAFE0A7565088101CC4AE31C5C8C74461CB + keyref .....: PIV.9D (encr) + algorithm ..: rsa2048 + used for ...: X.509 + user id ..: CN=Encryption key for yk-9074625,O=example,C=DE + user id ..: <otto@@example.net> +@end example + +It is now possible to sign and to encrypt with this card using gpgsm +and to use the @samp{PIV authentication} key with ssh: + +@example +$ ssh-add -l +384 SHA256:0qnJ0Y0ehWxKcx2frLfEljf6GCdlO55OZed5HqGHsaU cardno:yk-9074625 (ECDSA) +@end example + +As usual use ssh-add with the uppercase @samp{-L} to list the public +ssh key. To use the certificates with Thunderbird or Mozilla, please +consult the Scute manual for details. + + + +@c @mansect examples + +@mansect see also +@ifset isman +@command{scdaemon}(1) +@end ifset diff --git a/doc/gpg.texi b/doc/gpg.texi index 7f55cc7e3..e6829b911 100644 --- a/doc/gpg.texi +++ b/doc/gpg.texi @@ -624,9 +624,9 @@ fingerprint (preferred) or their keyid. @end table -@c ******************************************* -@c ******* KEY MANGEMENT COMMANDS ********** -@c ******************************************* +@c ******************************************** +@c ******* KEY MANAGEMENT COMMANDS ********** +@c ******************************************** @node OpenPGP Key Management @subsection How to manage your keys @@ -1328,6 +1328,10 @@ give the opposite meaning. The options are: meaningful when using @option{--with-colons} along with @option{--check-signatures}. + @item show-only-fpr-mbox + @opindex list-options:show-only-fpr-mbox + For each valid user-id which also has a valid mail address print + only the fingerprint and the mail address. @end table @item --verify-options @var{parameters} @@ -1724,7 +1728,8 @@ Set what trust model GnuPG should follow. The models are: @opindex trust-model:auto Select the trust model depending on whatever the internal trust database says. This is the default model if such a database already - exists. + exists. Note that a tofu trust model is not considered here and + must be enabled explicitly. @end table @item --auto-key-locate @var{mechanisms} @@ -1782,7 +1787,9 @@ list. The default is "local,wkd". @item clear Clear all defined mechanisms. This is useful to override - mechanisms given in a config file. + mechanisms given in a config file. Note that a @code{nodefault} in + @var{mechanisms} will also be cleared unless it is given after the + @code{clear}. @end table @@ -1888,32 +1895,12 @@ are available for all keyserver types, some common options are: retrieving keys by subkey id. @item timeout - Tell the keyserver helper program how long (in seconds) to try and - perform a keyserver action before giving up. Note that performing - multiple actions at the same time uses this timeout value per action. - For example, when retrieving multiple keys via @option{--receive-keys}, the - timeout applies separately to each key retrieval, and not to the - @option{--receive-keys} command as a whole. Defaults to 30 seconds. - - @item http-proxy=@var{value} - This option is deprecated. - Set the proxy to use for HTTP and HKP keyservers. - This overrides any proxy defined in @file{dirmngr.conf}. - - @item verbose - This option has no more function since GnuPG 2.1. Use the - @code{dirmngr} configuration options instead. - - @item debug - This option has no more function since GnuPG 2.1. Use the - @code{dirmngr} configuration options instead. - - @item check-cert - This option has no more function since GnuPG 2.1. Use the - @code{dirmngr} configuration options instead. - + @itemx http-proxy=@var{value} + @itemx verbose + @itemx debug + @itemx check-cert @item ca-cert-file - This option has no more function since GnuPG 2.1. Use the + These options have no more function since GnuPG 2.1. Use the @code{dirmngr} configuration options instead. @end table @@ -2342,6 +2329,11 @@ opposite meaning. The options are: on the keyring. This option is the same as running the @option{--edit-key} command "clean" after import. Defaults to no. + @item import-drop-uids + Do not import any user ids or their binding signatures. This option + can be used to update only the subkeys or other non-user id related + information. + @item repair-keys. After import, fix various problems with the keys. For example, this reorders signatures, and strips duplicate signatures. Defaults to yes. @@ -2506,6 +2498,11 @@ opposite meaning. The options are: running the @option{--edit-key} command "minimize" before export except that the local copy of the key is not modified. Defaults to no. + @item export-drop-uids + Do no export any user id or attribute packets or their associates + signatures. Note that due to missing user ids the resulting output is + not strictly RFC-4880 compliant. + @item export-pka Instead of outputting the key material output PKA records suitable to put into DNS zone files. An ORIGIN line is printed before each @@ -2612,7 +2609,7 @@ These options are obsolete and have no effect since GnuPG 2.1. @item --force-aead @opindex force-aead Force the use of AEAD encryption over MDC encryption. AEAD is a -modern and faster way to do authenticated encrytion than the old MDC +modern and faster way to do authenticated encryption than the old MDC method. See also options @option{--aead-algo} and @option{--chunk-size}. @@ -2768,7 +2765,7 @@ This option is obsolete; it is handled as an alias for @option{--pgp7} @item --pgp7 @opindex pgp7 -Set up all options to be as PGP 7 compliant as possible. This allowd +Set up all options to be as PGP 7 compliant as possible. This allowed the ciphers IDEA, 3DES, CAST5,AES128, AES192, AES256, and TWOFISH., the hashes MD5, SHA1 and RIPEMD160, and the compression algorithms none and ZIP. This option implies @option{--escape-from-lines} and @@ -3040,7 +3037,7 @@ same thing. @opindex aead-algo Specify that the AEAD algorithm @var{name} is to be used. This is useful for symmetric encryption where no key preference are available -to select the AEAD algorithm. Runing @command{@gpgname} with option +to select the AEAD algorithm. Running @command{@gpgname} with option @option{--version} shows the available AEAD algorithms. In general, you do not want to use this option as it allows you to violate the OpenPGP standard. The option @option{--personal-aead-preferences} is @@ -3313,7 +3310,7 @@ command has the same effect as using @option{--list-keys} with @option{--with-sig-list}. Note that in contrast to @option{--check-signatures} the key signatures are not verified. This command can be used to create a list of signing keys missing in the -lcoal keyring; for example: +local keyring; for example: @example gpg --list-sigs --with-colons USERID | \ diff --git a/doc/gpgv.texi b/doc/gpgv.texi index a05286171..2dd9576b6 100644 --- a/doc/gpgv.texi +++ b/doc/gpgv.texi @@ -59,13 +59,14 @@ no configuration files and only a few options are implemented. That does also mean that it does not check for expired or revoked keys. -By default a keyring named @file{trustedkeys.kbx} is used; if that -does not exist a keyring named @file{trustedkeys.gpg} is used. The -default keyring is assumed to be in the home directory of GnuPG, -either the default home directory or the one set by an option or an -environment variable. The option @code{--keyring} may be used to -specify a different keyring or even multiple keyrings. - +If no @code{--keyring} option is given, @code{gpgv} looks for a +``default'' keyring named @file{trustedkeys.kbx} (preferred) or +@file{trustedkeys.gpg} in the home directory of GnuPG, either the +default home directory or the one set by the @code{--homedir} option +or the @code{GNUPGHOME} environment variable. If any @code{--keyring} +option is used, @code{gpgv} will not look for the default keyring. The +@code{--keyring} option may be used multiple times and all specified +keyrings will be used together. @noindent @mansect options diff --git a/doc/specify-user-id.texi b/doc/specify-user-id.texi index b363c2ace..64e354bdf 100644 --- a/doc/specify-user-id.texi +++ b/doc/specify-user-id.texi @@ -135,7 +135,7 @@ RFC-2253 encoded DN of the issuer. See note above. @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}. It does not yet work for OpenPGP keys. +@option{--dump-cert}. @cartouche @example @@ -171,6 +171,3 @@ 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. - - - diff --git a/doc/tools.texi b/doc/tools.texi index 7becf67e2..119f698d6 100644 --- a/doc/tools.texi +++ b/doc/tools.texi @@ -1561,7 +1561,7 @@ string @code{true} or @code{yes}. The evaluation is done by passing /subst /let i 3 /while $i - /echo loop couter is $i + /echo loop counter is $i /let i $@{- $i 1@} /end @end smallexample @@ -1962,7 +1962,7 @@ Extract all files from an encrypted archive. @item --sign @itemx -s -Make a signed archive from the given files and directories. Thsi can +Make a signed archive from the given files and directories. This can be combined with option @option{--encrypt} to create a signed and then encrypted archive. @@ -2014,10 +2014,11 @@ Do not actually output the extracted files. @item --directory @var{dir} @itemx -C @var{dir} @opindex directory -Extract the files into the directory @var{dir}. The -default is to take the directory name from -the input filename. If no input filename is known a directory named -@file{GPGARCH} is used. +Extract the files into the directory @var{dir}. The default is to +take the directory name from the input filename. If no input filename +is known a directory named @file{GPGARCH} is used. For tarball +creation, switch to directory @var{dir} before performing any +operations. @item --files-from @var{file} @itemx -T @var{file} @@ -2031,7 +2032,7 @@ linefeed to separate file names. @item --openpgp @opindex openpgp -This option has no effect becuase OpenPGP encryption and signing is +This option has no effect because OpenPGP encryption and signing is the default. @item --cms diff --git a/doc/wks.texi b/doc/wks.texi index 4508ae2a1..f132b3186 100644 --- a/doc/wks.texi +++ b/doc/wks.texi @@ -61,11 +61,12 @@ Service provider. This is usuallay done to upload a key into a Web Key Directory. With the @option{--supported} command the caller can test whether a -site supports the Web Key Service. The argument is an arbitray +site supports the Web Key Service. The argument is an arbitrary address in the to be tested domain. For example @file{foo@@example.net}. The command returns success if the Web Key Service is supported. The operation is silent; to get diagnostic -output use the option @option{--verbose}. +output use the option @option{--verbose}. See option +@option{--with-colons} for a variant of this command. With the @option{--check} command the caller can test whether a key exists for a supplied mail address. The command returns success if a @@ -89,6 +90,17 @@ decrypted MIME message. The result of these commands are another mail which can be send in the same way as the mail created with @option{--create}. +The command @option{--install-key} manually installs a key into a +local directory (see option @option{-C}) reflecting the structure of a +WKD. The arguments are a file with the keyblock and the user-id to +install. If the first argument resembles a fingerprint the key is +taken from the current keyring; to force the use of a file, prefix the +first argument with "./". If no arguments are given the parameters +are read from stdin; the expected format are lines with the +fingerprint and the mailbox separated by a space. The command +@option{--remove-key} removes a key from that directory, its only +argument is a user-id. + @command{gpg-wks-client} is not commonly invoked directly and thus it is not installed in the bin directory. Here is an example how it can be invoked manually to check for a Web Key Directory entry for @@ -109,6 +121,44 @@ $(gpgconf --list-dirs libexecdir)/gpg-wks-client --check foo@@example.net Directly send created mails using the @command{sendmail} command. Requires installation of that command. +@item --with-colons +@opindex with-colons +This option has currently only an effect on the @option{--supported} +command. If it is used all arguments on the command line are taken +as domain names and tested for WKD support. The output format is one +line per domain with colon delimited fields. The currently specified +fields are (future versions may specify additional fields): + +@table @asis + + @item 1 - domain + This is the domain name. Although quoting is not required for valid + domain names this field is specified to be quoted in standard C + manner. + + @item 2 - WKD + If the value is true the domain supports the Web Key Directory. + + @item 3 - WKS + If the value is true the domain supports the Web Key Service + protocol to upload keys to the directory. + + @item 4 - error-code + This may contain an gpg-error code to describe certain + failures. Use @samp{gpg-error CODE} to explain the code. + + @item 5 - protocol-version + The minimum protocol version supported by the server. + + @item 6 - auth-submit + The auth-submit flag from the policy file of the server. + + @item 7 - mailbox-only + The mailbox-only flag from the policy file of the server. +@end table + + + @item --output @var{file} @itemx -o @opindex output @@ -122,6 +172,13 @@ This program returns only the status messages SUCCESS or FAILURE which are helpful when the caller uses a double fork approach and can't easily get the return code of the process. +@item -C @var{dir} +@itemx --directory @var{dir} +@opindex directory +Use @var{dir} as top level directory for the commands +@option{--install-key} and @option{--remove-key}. The default is +@file{openpgpkey}. + @item --verbose @opindex verbose Enable extra informational output. @@ -206,7 +263,7 @@ mail is processed. Commonly this command is used with the option @option{--send} to directly send the crerated mails back. See below for an installation example. -The command @option{--cron} is used for regualr cleanup tasks. For +The command @option{--cron} is used for regular cleanup tasks. For example non-confirmed requested should be removed after their expire time. It is best to run this command once a day from a cronjob. @@ -215,9 +272,9 @@ Further it creates missing directories for the configuration and prints warnings pertaining to problems in the configuration. The command @option{--check-key} (or just @option{--check}) checks -whether a key with the given user-id is installed. The process return -success in this case; to also print a diagnostic, use option -@option{-v}. If the key is not installed a diagnostics is printed and +whether a key with the given user-id is installed. The process returns +success in this case; to also print a diagnostic use the option +@option{-v}. If the key is not installed a diagnostic is printed and the process returns failure; to suppress the diagnostic, use option @option{-q}. More than one user-id can be given; see also option @option{with-file}. @@ -226,7 +283,9 @@ The command @option{--install-key} manually installs a key into the WKD. The arguments are a file with the keyblock and the user-id to install. If the first argument resembles a fingerprint the key is taken from the current keyring; to force the use of a file, prefix the -first argument with "./". +first argument with "./". If no arguments are given the parameters +are read from stdin; the expected format are lines with the +fingerprint and the mailbox separated by a space. The command @option{--remove-key} uninstalls a key from the WKD. The process returns success in this case; to also print a diagnostic, use @@ -243,6 +302,12 @@ The command @option{--revoke-key} is not yet functional. @table @gnupgtabopt +@item -C @var{dir} +@itemx --directory @var{dir} +@opindex directory +Use @var{dir} as top level directory for domains. The default is +@file{/var/lib/gnupg/wks}. + @item --from @var{mailaddr} @opindex from Use @var{mailaddr} as the default sender address. @@ -256,21 +321,22 @@ Add the mail header "@var{name}: @var{value}" to all outgoing mails. Directly send created mails using the @command{sendmail} command. Requires installation of that command. -@item --output @var{file} -@itemx -o +@item -o @var{file} +@itemx --output @var{file} @opindex output Write the created mail also to @var{file}. Note that the value @code{-} for @var{file} would write it to stdout. @item --with-dir @opindex with-dir -Also print the directory name for each domain listed by command -@option{--list-domains}. +When used with the command @option{--list-domains} print for each +installed domain the domain name and its directory name. @item --with-file @opindex with-file -With command @option{--check-key} print for each user-id, the address, -'i' for installed key or 'n' for not installed key, and the filename. +When used with the command @option{--check-key} print for each user-id, +the address, 'i' for installed key or 'n' for not installed key, and +the filename. @item --verbose @opindex verbose @@ -316,7 +382,7 @@ Finally run $ gpg-wks-server --list-domains @end example -to create the required sub-directories with the permission set +to create the required sub-directories with the permissions set correctly. For each domain a submission address needs to be configured. All service mails are directed to that address. It can be the same address for all configured domains, for example: @@ -326,7 +392,7 @@ be the same address for all configured domains, for example: $ echo key-submission@@example.net >submission-address @end example -The protocol requires that the key to be published is sent with an +The protocol requires that the key to be published is send with an encrypted mail to the service. Thus you need to create a key for the submission address: diff --git a/doc/yat2m.c b/doc/yat2m.c index c7bec338f..be0ef17fd 100644 --- a/doc/yat2m.c +++ b/doc/yat2m.c @@ -55,7 +55,7 @@ .B whateever you want @end ifset - alternativly a special comment may be used: + alternatively a special comment may be used: @c man:.B whatever you want @@ -704,7 +704,7 @@ write_th (FILE *fp) /* Process the texinfo command COMMAND (without the leading @) and - write output if needed to FP. REST is the remainer of the line + write output if needed to FP. REST is the remainder of the line which should either point to an opening brace or to a white space. The function returns the number of characters already processed from REST. LEN is the usable length of REST. TABLE_LEVEL is used to @@ -1197,7 +1197,7 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause) if (*p == '@' && !strncmp (p+1, "item", 4)) item_indent = p - line; /* Set a new indent level. */ else if (p - line < item_indent) - item_indent = 0; /* Switch off indention. */ + item_indent = 0; /* Switch off indentation. */ if (item_indent) { |