1 This is /home/wk/w/gnupg-stable/doc/gnupg.info, produced by makeinfo
2 version 4.13 from /home/wk/w/gnupg-stable/doc/gnupg.texi.
4 This is the `The GNU Privacy Guard Manual' (version 2.0.19,
7 Copyright (C) 2002, 2004, 2005, 2006, 2007, 2010 Free Software
10 Permission is granted to copy, distribute and/or modify this
11 document under the terms of the GNU General Public License as
12 published by the Free Software Foundation; either version 3 of the
13 License, or (at your option) any later version. The text of the
14 license can be found in the section entitled "Copying".
16 INFO-DIR-SECTION GNU Utilities
18 * gpg2: (gnupg). OpenPGP encryption and signing tool.
19 * gpgsm: (gnupg). S/MIME encryption and signing tool.
20 * gpg-agent: (gnupg). The secret key daemon.
24 File: gnupg.info, Node: Top, Next: Installation, Up: (dir)
26 Using the GNU Privacy Guard
27 ***************************
29 This is the `The GNU Privacy Guard Manual' (version 2.0.19,
32 Copyright (C) 2002, 2004, 2005, 2006, 2007, 2010 Free Software
35 Permission is granted to copy, distribute and/or modify this
36 document under the terms of the GNU General Public License as
37 published by the Free Software Foundation; either version 3 of the
38 License, or (at your option) any later version. The text of the
39 license can be found in the section entitled "Copying".
41 This manual documents how to use the GNU Privacy Guard system as
42 well as the administration and the architecture.
46 * Installation:: A short installation guide.
48 * Invoking GPG-AGENT:: How to launch the secret key daemon.
49 * Invoking GPG:: Using the OpenPGP protocol.
50 * Invoking GPGSM:: Using the S/MIME protocol.
51 * Invoking SCDAEMON:: How to handle Smartcards.
52 * Specify a User ID:: How to Specify a User Id.
54 * Helper Tools:: Description of small helper tools
56 * Howtos:: How to do certain things.
57 * System Notes:: Notes pertaining to certain OSes.
58 * Debugging:: How to solve problems
60 * Copying:: GNU General Public License says
61 how you can copy and share GnuPG
62 * Contributors:: People who have contributed to GnuPG.
64 * Glossary:: Short description of terms used.
65 * Option Index:: Index to command line options.
66 * Index:: Index of concepts and symbol names.
69 File: gnupg.info, Node: Installation, Next: Invoking GPG-AGENT, Prev: Top, Up: Top
71 1 A short installation guide.
72 *****************************
74 Unfortunately the installation guide has not been finished in time.
75 Instead of delaying the release of GnuPG 2.0 even further, I decided to
76 release without that guide. The chapter on gpg-agent and gpgsm do
77 include brief information on how to set up the whole thing. Please
78 watch the GnuPG website for updates of the documentation. In the
79 meantime you may search the GnuPG mailing list archives or ask on the
80 gnupg-users mailing listsfor advise on how to solve problems or how to
81 get that whole thing up and running.
83 ** Building the software
85 Building the software is decribed in the file `INSTALL'. Given that
86 you are already reading this documentation we can only give some extra
89 To comply with the rules on GNU systems you should have build time
90 configured `dirmngr' using:
92 ./configure --sysconfdir=/etc --localstatedir=/var
94 This is to make sure that system wide configuration files are
95 searched in the directory `/etc/gnupg' and variable data below `/var';
96 the default would be to also install them below `/usr/local' where the
97 binaries get installed. If you selected to use the `--prefix=/' you
98 obviously don't need those option as they are the default then.
100 ** Explain how to setup a root CA key as trusted
102 Such questions may also help to write a proper installation guide.
106 XXX Tell how to setup the system, install certificates, how dirmngr
107 relates to GnuPG etc.
109 ** Explain how to setup a root CA key as trusted
111 X.509 is based on a hierarchical key infrastructure. At the root of
112 the tree a trusted anchor (root certificate) is required. There are
113 usually no other means of verifying whether this root certificate is
114 trustworthy than looking it up in a list. GnuPG uses a file
115 (`trustlist.txt') to keep track of all root certificates it knows
116 about. There are 3 ways to get certificates into this list:
118 * Use the list which comes with GnuPG. However this list only
119 contains a few root certificates. Most installations will need
122 * Let `gpgsm' ask you whether you want to insert a new root
123 certificate. To enable this feature you need to set the option
124 `allow-mark-trusted' into `gpg-agent.conf'. In general it is not
125 a good idea to do it this way. Checking whether a root
126 certificate is really trustworthy requires decisions, which casual
127 users are not up to. Thus, by default this option is not enabled.
129 * Manually maintain the list of trusted root certificates. For a
130 multi user installation this can be done once for all users on a
131 machine. Specific changes on a per-user base are also possible.
133 XXX decribe how to maintain trustlist.txt and
134 /etc/gnupg/trustlist.txt.
136 ** How to get the ssh support running
138 XXX How to use the ssh support.
140 1.1 Installation Overview
141 =========================
146 File: gnupg.info, Node: Invoking GPG-AGENT, Next: Invoking GPG, Prev: Installation, Up: Top
151 `gpg-agent' is a daemon to manage secret (private) keys independently
152 from any protocol. It is used as a backend for `gpg' and `gpgsm' as
153 well as for a couple of other utilities.
155 The usual way to run the agent is from the `~/.xsession' file:
157 eval $(gpg-agent --daemon)
158 If you don't use an X server, you can also put this into your regular
159 startup file `~/.profile' or `.bash_profile'. It is best not to run
160 multiple instance of the `gpg-agent', so you should make sure that only
161 one is running: `gpg-agent' uses an environment variable to inform
162 clients about the communication parameters. You can write the content
163 of this environment variable to a file so that you can test for a
164 running agent. Here is an example using Bourne shell syntax:
166 gpg-agent --daemon --enable-ssh-support \
167 --write-env-file "${HOME}/.gpg-agent-info"
169 This code should only be run once per user session to initially fire
170 up the agent. In the example the optional support for the included
171 Secure Shell agent is enabled and the information about the agent is
172 written to a file in the HOME directory. Note that by running
173 gpg-agent without arguments you may test whether an agent is already
174 running; however such a test may lead to a race condition, thus it is
177 The second script needs to be run for each interactive session:
179 if [ -f "${HOME}/.gpg-agent-info" ]; then
180 . "${HOME}/.gpg-agent-info"
181 export GPG_AGENT_INFO
185 It reads the data out of the file and exports the variables. If you
186 don't use Secure Shell, you don't need the last two export statements.
188 You should always add the following lines to your `.bashrc' or whatever
189 initialization file is used for all shell invocations:
194 It is important that this environment variable always reflects the
195 output of the `tty' command. For W32 systems this option is not
198 Please make sure that a proper pinentry program has been installed
199 under the default filename (which is system dependant) or use the
200 option `pinentry-program' to specify the full name of that program. It
201 is often useful to install a symbolic link from the actual used
202 pinentry (e.g. `/usr/bin/pinentry-gtk') to the expected one (e.g.
203 `/usr/bin/pinentry').
205 *Note Option Index::,for an index to `GPG-AGENT''s commands and options.
209 * Agent Commands:: List of all commands.
210 * Agent Options:: List of all options.
211 * Agent Configuration:: Configuration files.
212 * Agent Signals:: Use of some signals.
213 * Agent Examples:: Some usage examples.
214 * Agent Protocol:: The protocol the agent uses.
217 File: gnupg.info, Node: Agent Commands, Next: Agent Options, Up: Invoking GPG-AGENT
222 Commands are not distinguished from options except for the fact that
223 only one command is allowed.
226 Print the program version and licensing information. Note that
227 you cannot abbreviate this command.
231 Print a usage message summarizing the most useful command-line
232 options. Note that you cannot abbreviate this command.
235 Print a list of all available options and commands. Note that you
236 cannot abbreviate this command.
239 Run in server mode and wait for commands on the `stdin'. The
240 default mode is to create a socket and listen for commands there.
242 `--daemon [COMMAND LINE]'
243 Start the gpg-agent as a daemon; that is, detach it from the
244 console and run it in the background. Because `gpg-agent' prints
245 out important information required for further use, a common way of
246 invoking gpg-agent is: `eval $(gpg-agent --daemon)' to setup the
247 environment variables. The option `--write-env-file' is another
248 way commonly used to do this. Yet another way is creating a new
249 process as a child of gpg-agent: `gpg-agent --daemon /bin/sh'.
250 This way you get a new shell with the environment setup properly;
251 if you exit from this shell, gpg-agent terminates as well.
254 File: gnupg.info, Node: Agent Options, Next: Agent Configuration, Prev: Agent Commands, Up: Invoking GPG-AGENT
260 Reads configuration from FILE instead of from the default per-user
261 configuration file. The default configuration file is named
262 `gpg-agent.conf' and expected in the `.gnupg' directory directly
263 below the home directory of the user.
266 Set the name of the home directory to DIR. If this option is not
267 used, the home directory defaults to `~/.gnupg'. It is only
268 recognized when given on the command line. It also overrides any
269 home directory stated through the environment variable `GNUPGHOME'
270 or (on W32 systems) by means of the Registry entry
271 HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
276 Outputs additional information while running. You can increase
277 the verbosity by giving several verbose commands to `gpgsm', such
283 Try to be as quiet as possible.
286 Don't invoke a pinentry or do any other thing requiring human
289 `--faked-system-time EPOCH'
290 This option is only useful for testing; it sets the system time
291 back or forth to EPOCH which is the number of seconds elapsed
294 `--debug-level LEVEL'
295 Select the debug level for investigating problems. LEVEL may be a
296 numeric value or a keyword:
299 No debugging at all. A value of less than 1 may be used
300 instead of the keyword.
303 Some basic debug messages. A value between 1 and 2 may be
304 used instead of the keyword.
307 More verbose debug messages. A value between 3 and 5 may be
308 used instead of the keyword.
311 Even more detailed messages. A value between 6 and 8 may be
312 used instead of the keyword.
315 All of the debug messages you can get. A value greater than 8
316 may be used instead of the keyword. The creation of hash
317 tracing files is only enabled if the keyword is used.
319 How these messages are mapped to the actual debugging flags is not
320 specified and may change with newer releases of this program. They
321 are however carefully selected to best aid in debugging.
324 This option is only useful for debugging and the behaviour may
325 change at any time without notice. FLAGS are bit encoded and may
326 be given in usual C-Syntax. The currently defined bits are:
329 X.509 or OpenPGP protocol related data
332 values of big number integers
335 low level crypto operations
344 show memory statistics.
347 write hashed data to files named `dbgmd-000*'
350 trace Assuan protocol
353 bypass all certificate validation
356 Same as `--debug=0xffffffff'
359 When running in server mode, wait N seconds before entering the
360 actual processing loop and print the pid. This gives time to
364 Don't detach the process from the console. This is mainly useful
371 Format the info output in daemon mode for use with the standard
372 Bourne shell or the C-shell respectively. The default is to guess
373 it based on the environment variable `SHELL' which is correct in
376 `--write-env-file FILE'
377 Often it is required to connect to the agent from a process not
378 being an inferior of `gpg-agent' and thus the environment variable
379 with the socket name is not available. To help setting up those
380 variables in other sessions, this option may be used to write the
381 information into FILE. If FILE is not specified the default name
382 `${HOME}/.gpg-agent-info' will be used. The format is suitable to
383 be evaluated by a Bourne shell like in this simple example:
386 eval $(cut -d= -f 1 < FILE | xargs echo export)
389 Tell the pinentry not to grab the keyboard and mouse. This option
390 should in general not be used to avoid X-sniffing attacks.
393 Append all logging output to FILE. This is very helpful in seeing
394 what the agent actually does. If neither a log file nor a log file
395 descriptor has been set on a Windows platform, the Registry entry
396 `HKCU\Software\GNU\GnuPG:DefaultLogFile', if set, is used to
397 specify the logging output.
399 `--allow-mark-trusted'
400 Allow clients to mark keys as trusted, i.e. put them into the
401 `trustlist.txt' file. This is by default not allowed to make it
402 harder for users to inadvertently accept Root-CA keys.
404 `--ignore-cache-for-signing'
405 This option will let `gpg-agent' bypass the passphrase cache for
406 all signing operation. Note that there is also a per-session
407 option to control this behaviour but this command line option
410 `--default-cache-ttl N'
411 Set the time a cache entry is valid to N seconds. The default is
414 `--default-cache-ttl-ssh N'
415 Set the time a cache entry used for SSH keys is valid to N
416 seconds. The default is 1800 seconds.
419 Set the maximum time a cache entry is valid to N seconds. After
420 this time a cache entry will be expired even if it has been
421 accessed recently. The default is 2 hours (7200 seconds).
423 `--max-cache-ttl-ssh N'
424 Set the maximum time a cache entry used for SSH keys is valid to N
425 seconds. After this time a cache entry will be expired even if it
426 has been accessed recently. The default is 2 hours (7200 seconds).
428 `--enforce-passphrase-constraints'
429 Enforce the passphrase constraints by not allowing the user to
430 bypass them using the "Take it anyway" button.
432 `--min-passphrase-len N'
433 Set the minimal length of a passphrase. When entering a new
434 passphrase shorter than this value a warning will be displayed.
437 `--min-passphrase-nonalpha N'
438 Set the minimal number of digits or special characters required in
439 a passphrase. When entering a new passphrase with less than this
440 number of digits or special characters a warning will be
441 displayed. Defaults to 1.
443 `--check-passphrase-pattern FILE'
444 Check the passphrase against the pattern given in FILE. When
445 entering a new passphrase matching one of these pattern a warning
446 will be displayed. FILE should be an absolute filename. The
447 default is not to use any pattern file.
449 Security note: It is known that checking a passphrase against a
450 list of pattern or even against a complete dictionary is not very
451 effective to enforce good passphrases. Users will soon figure up
452 ways to bypass such a policy. A better policy is to educate users
453 on good security behavior and optionally to run a passphrase
454 cracker regularly on all users passphrases to catch the very
457 `--max-passphrase-days N'
458 Ask the user to change the passphrase if N days have passed since
459 the last change. With `--enforce-passphrase-constraints' set the
460 user may not bypass this check.
462 `--enable-passphrase-history'
463 This option does nothing yet.
465 `--pinentry-program FILENAME'
466 Use program FILENAME as the PIN entry. The default is installation
469 `--pinentry-touch-file FILENAME'
470 By default the filename of the socket gpg-agent is listening for
471 requests is passed to Pinentry, so that it can touch that file
472 before exiting (it does this only in curses mode). This option
473 changes the file passed to Pinentry to FILENAME. The special name
474 `/dev/null' may be used to completely disable this feature. Note
475 that Pinentry will not create that file, it will only change the
476 modification and access time.
478 `--scdaemon-program FILENAME'
479 Use program FILENAME as the Smartcard daemon. The default is
480 installation dependent and can be shown with the `gpgconf' command.
483 Do not make use of the scdaemon tool. This option has the effect
484 of disabling the ability to do smartcard operations. Note, that
485 enabling this option at runtime does not kill an already forked
488 `--use-standard-socket'
489 `--no-use-standard-socket'
490 By enabling this option `gpg-agent' will listen on the socket
491 named `S.gpg-agent', located in the home directory, and not create
492 a random socket below a temporary directory. Tools connecting to
493 `gpg-agent' should first try to connect to the socket given in
494 environment variable GPG_AGENT_INFO and then fall back to this
495 socket. This option may not be used if the home directory is
496 mounted on a remote file system which does not support special
497 files like fifos or sockets. Note, that `--use-standard-socket'
498 is the default on Windows systems. The default may be changed at
499 build time. It is possible to test at runtime whether the agent
500 has been configured for use with the standard socket by issuing
501 the command `gpg-agent --use-standard-socket-p' which returns
502 success if the standard socket option has been enabled.
508 `--lc-messages STRING'
509 `--xauthority STRING'
510 These options are used with the server mode to pass localization
515 Ignore requests to change the current `tty' or X window system's
516 `DISPLAY' variable respectively. This is useful to lock the
517 pinentry to pop up at the `tty' or display you started the agent.
519 `--enable-ssh-support'
520 Enable the OpenSSH Agent protocol.
522 In this mode of operation, the agent does not only implement the
523 gpg-agent protocol, but also the agent protocol used by OpenSSH
524 (through a separate socket). Consequently, it should be possible
525 to use the gpg-agent as a drop-in replacement for the well known
528 SSH Keys, which are to be used through the agent, need to be added
529 to the gpg-agent initially through the ssh-add utility. When a
530 key is added, ssh-add will ask for the password of the provided
531 key file and send the unprotected key material to the agent; this
532 causes the gpg-agent to ask for a passphrase, which is to be used
533 for encrypting the newly received key and storing it in a
534 gpg-agent specific directory.
536 Once a key has been added to the gpg-agent this way, the gpg-agent
537 will be ready to use the key.
539 Note: in case the gpg-agent receives a signature request, the user
540 might need to be prompted for a passphrase, which is necessary for
541 decrypting the stored key. Since the ssh-agent protocol does not
542 contain a mechanism for telling the agent on which
543 display/terminal it is running, gpg-agent's ssh-support will use
544 the TTY or X display where gpg-agent has been started. To switch
545 this display to the current one, the following command may be used:
547 gpg-connect-agent updatestartuptty /bye
549 Although all GnuPG components try to start the gpg-agent as
550 needed, this is not possible for the ssh support because ssh does
551 not know about it. Thus if no GnuPG tool which accesses the agent
552 has been run, there is no guarantee that ssh is abale to use
553 gpg-agent for authentication. To fix this you may start gpg-agent
554 if needed using this simple command:
556 gpg-connect-agent /bye
558 Adding the `--verbose' shows the progress of starting the agent.
561 All the long options may also be given in the configuration file
562 after stripping off the two leading dashes.
565 File: gnupg.info, Node: Agent Configuration, Next: Agent Signals, Prev: Agent Options, Up: Invoking GPG-AGENT
570 There are a few configuration files needed for the operation of the
571 agent. By default they may all be found in the current home directory
572 (*note option --homedir::).
575 This is the standard configuration file read by `gpg-agent' on
576 startup. It may contain any valid long option; the leading two
577 dashes may not be entered and the option may not be abbreviated.
578 This file is also read after a `SIGHUP' however only a few
579 options will actually have an effect. This default name may be
580 changed on the command line (*note option --options::). You
581 should backup this file.
584 This is the list of trusted keys. You should backup this file.
586 Comment lines, indicated by a leading hash mark, as well as empty
587 lines are ignored. To mark a key as trusted you need to enter its
588 fingerprint followed by a space and a capital letter `S'. Colons
589 may optionally be used to separate the bytes of a fingerprint;
590 this allows to cut and paste the fingerprint from a key listing
591 output. If the line is prefixed with a `!' the key is
592 explicitly marked as not trusted.
594 Here is an example where two keys are marked as ultimately trusted
595 and one as not trusted:
597 # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
598 A6935DD34EF3087973C706FC311AA2CCF733765B S
600 # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
601 DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S
603 # CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
604 !14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S
606 Before entering a key into this file, you need to ensure its
607 authenticity. How to do this depends on your organisation; your
608 administrator might have already entered those keys which are
609 deemed trustworthy enough into this file. Places where to look
610 for the fingerprint of a root certificate are letters received
611 from the CA or the website of the CA (after making 100% sure that
612 this is indeed the website of that CA). You may want to consider
613 allowing interactive updates of this file by using the *Note
614 option --allow-mark-trusted::. This is however not as secure as
615 maintaining this file manually. It is even advisable to change
616 the permissions to read-only so that this file can't be changed
619 As a special feature a line `include-default' will include a global
620 list of trusted certificates (e.g. `/etc/gnupg/trustlist.txt').
621 This global list is also used if the local list is not available.
623 It is possible to add further flags after the `S' for use by the
627 Relax checking of some root certificate requirements. As of
628 now this flag allows the use of root certificates with a
629 missing basicConstraints attribute (despite that it is a MUST
630 for CA certificates) and disables CRL checking for the root
634 If validation of a certificate finally issued by a CA with
635 this flag set fails, try again using the chain validation
640 This file is used when support for the secure shell agent protocol
641 has been enabled (*note option --enable-ssh-support::). Only keys
642 present in this file are used in the SSH protocol. You should
645 The `ssh-add' tool may be used to add new entries to this file;
646 you may also add them manually. Comment lines, indicated by a
647 leading hash mark, as well as empty lines are ignored. An entry
648 starts with optional whitespace, followed by the keygrip of the
649 key given as 40 hex digits, optionally followed by the caching TTL
650 in seconds and another optional field for arbitrary flags. A
651 non-zero TTL overrides the global default as set by
652 `--default-cache-ttl-ssh'.
654 The only flag support is `confirm'. If this flag is found for a
655 key, each use of the key will pop up a pinentry to confirm the use
656 of that key. The flag is automatically set if a new key was
657 loaded into `gpg-agent' using the option `-c' of the `ssh-add'
660 The keygrip may be prefixed with a `!' to disable an entry entry.
662 The following example lists exactly one key. Note that keys
663 available through a OpenPGP smartcard in the active smartcard
664 reader are implicitly added to this list; i.e. there is no need to
667 # Key added on: 2011-07-20 20:38:46
668 # Fingerprint: 5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81
669 34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm
672 This is the directory where gpg-agent stores the private keys.
673 Each key is stored in a file with the name made up of the
674 keygrip and the suffix `key'. You should backup all files in
675 this directory and take great care to keep this backup closed
679 Note that on larger installations, it is useful to put predefined
680 files into the directory `/etc/skel/.gnupg/' so that newly created
681 users start up with a working configuration. For existing users the a
682 small helper script is provided to create these files (*note
686 File: gnupg.info, Node: Agent Signals, Next: Agent Examples, Prev: Agent Configuration, Up: Invoking GPG-AGENT
688 2.4 Use of some signals.
689 ========================
691 A running `gpg-agent' may be controlled by signals, i.e. using the
692 `kill' command to send a signal to the process.
694 Here is a list of supported signals:
697 This signal flushes all cached passphrases and if the program has
698 been started with a configuration file, the configuration file is
699 read again. Only certain options are honored: `quiet', `verbose',
700 `debug', `debug-all', `debug-level', `no-grab',
701 `pinentry-program', `default-cache-ttl', `max-cache-ttl',
702 `ignore-cache-for-signing', `allow-mark-trusted' and
703 `disable-scdaemon'. `scdaemon-program' is also supported but due
704 to the current implementation, which calls the scdaemon only once,
705 it is not of much use unless you manually kill the scdaemon.
708 Shuts down the process but waits until all current requests are
709 fulfilled. If the process has received 3 of these signals and
710 requests are still pending, a shutdown is forced.
713 Shuts down the process immediately.
716 Dump internal information to the log file.
719 This signal is used for internal purposes.
723 File: gnupg.info, Node: Agent Examples, Next: Agent Protocol, Prev: Agent Signals, Up: Invoking GPG-AGENT
728 The usual way to invoke `gpg-agent' is
730 $ eval $(gpg-agent --daemon)
732 An alternative way is by replacing `ssh-agent' with `gpg-agent'. If
733 for example `ssh-agent' is started as part of the Xsession
734 initialization, you may simply replace `ssh-agent' by a script like:
738 exec /usr/local/bin/gpg-agent --enable-ssh-support --daemon \
739 --write-env-file ${HOME}/.gpg-agent-info "$@"
741 and add something like (for Bourne shells)
743 if [ -f "${HOME}/.gpg-agent-info" ]; then
744 . "${HOME}/.gpg-agent-info"
745 export GPG_AGENT_INFO
749 to your shell initialization file (e.g. `~/.bashrc').
752 File: gnupg.info, Node: Agent Protocol, Prev: Agent Examples, Up: Invoking GPG-AGENT
754 2.6 Agent's Assuan Protocol
755 ===========================
757 Note: this section does only document the protocol, which is used by
758 GnuPG components; it does not deal with the ssh-agent protocol.
760 The `gpg-agent' should be started by the login shell and set an
761 environment variable to tell clients about the socket to be used.
762 Clients should deny to access an agent with a socket name which does
763 not match its own configuration. An application may choose to start an
764 instance of the gpgagent if it does not figure that any has been
765 started; it should not do this if a gpgagent is running but not usable.
766 Because `gpg-agent' can only be used in background mode, no special
767 command line option is required to activate the use of the protocol.
769 To identify a key we use a thing called keygrip which is the SHA-1
770 hash of an canonical encoded S-Expression of the public key as used in
771 Libgcrypt. For the purpose of this interface the keygrip is given as a
772 hex string. The advantage of using this and not the hash of a
773 certificate is that it will be possible to use the same keypair for
774 different protocols, thereby saving space on the token used to keep the
779 * Agent PKDECRYPT:: Decrypting a session key
780 * Agent PKSIGN:: Signing a Hash
781 * Agent GENKEY:: Generating a Key
782 * Agent IMPORT:: Importing a Secret Key
783 * Agent EXPORT:: Exporting a Secret Key
784 * Agent ISTRUSTED:: Importing a Root Certificate
785 * Agent GET_PASSPHRASE:: Ask for a passphrase
786 * Agent GET_CONFIRMATION:: Ask for confirmation
787 * Agent HAVEKEY:: Check whether a key is available
788 * Agent LEARN:: Register a smartcard
789 * Agent PASSWD:: Change a Passphrase
790 * Agent UPDATESTARTUPTTY:: Change the Standard Display
791 * Agent GETEVENTCOUNTER:: Get the Event Counters
792 * Agent GETINFO:: Return information about the process
793 * Agent OPTION:: Set options for the session
796 File: gnupg.info, Node: Agent PKDECRYPT, Next: Agent PKSIGN, Up: Agent Protocol
798 2.6.1 Decrypting a session key
799 ------------------------------
801 The client asks the server to decrypt a session key. The encrypted
802 session key should have all information needed to select the
803 appropriate secret key or to delegate it to a smartcard.
807 Tell the server about the key to be used for decryption. If this is
808 not used, `gpg-agent' may try to figure out the key by trying to
809 decrypt the message with each key available.
813 The agent checks whether this command is allowed and then does an
814 INQUIRY to get the ciphertext the client should then send the cipher
817 S: INQUIRE CIPHERTEXT
822 Please note that the server may send status info lines while reading
823 the data lines from the client. The data send is a SPKI like S-Exp with
828 (<param_name1> <mpi>)
830 (<param_namen> <mpi>)))
832 Where algo is a string with the name of the algorithm; see the
833 libgcrypt documentation for a list of valid algorithms. The number and
834 names of the parameters depend on the algorithm. The agent does return
835 an error if there is an inconsistency.
837 If the decryption was successful the decrypted data is returned by
840 Here is an example session:
843 S: INQUIRE CIPHERTEXT
844 C: D (enc-val elg (a 349324324)
845 C: D (b 3F444677CA)))
847 S: # session key follows
848 S: D (value 1234567890ABCDEF0)
849 S: OK descryption successful
852 File: gnupg.info, Node: Agent PKSIGN, Next: Agent GENKEY, Prev: Agent PKDECRYPT, Up: Agent Protocol
857 The client ask the agent to sign a given hash value. A default key
858 will be chosen if no key has been set. To set a key a client first
863 This can be used multiple times to create multiple signature, the
864 list of keys is reset with the next PKSIGN command or a RESET. The
865 server test whether the key is a valid key to sign something and
868 SETHASH --hash=<name>|<algo> <hexstring>
870 The client can use this command to tell the server about the data
871 <hexstring> (which usually is a hash) to be signed. <algo> is the
872 decimal encoded hash algorithm number as used by Libgcrypt. Either
873 <algo> or -hash=<name> must be given. Valid names for <name> are:
885 The actual signing is done using
889 Options are not yet defined, but my later be used to choose among
890 different algorithms. The agent does then some checks, asks for the
891 passphrase and as a result the server returns the signature as an SPKI
892 like S-expression in "D" lines:
896 (<param_name1> <mpi>)
898 (<param_namen> <mpi>)))
900 The operation is affected by the option
902 OPTION use-cache-for-signing=0|1
904 The default of `1' uses the cache. Setting this option to `0' will
905 lead `gpg-agent' to ignore the passphrase cache. Note, that there is
906 also a global command line option for `gpg-agent' to globally disable
909 Here is an example session:
916 S: # I did ask the user whether he really wants to sign
917 S: # I did ask the user for the passphrase
919 C: D ABCDEF012345678901234
921 S: # signature follows
922 S: D (sig-val rsa (s 45435453654612121212))
926 File: gnupg.info, Node: Agent GENKEY, Next: Agent IMPORT, Prev: Agent PKSIGN, Up: Agent Protocol
928 2.6.3 Generating a Key
929 ----------------------
931 This is used to create a new keypair and store the secret key inside the
932 active PSE -- which is in most cases a Soft-PSE. An not yet defined
933 option allows to choose the storage location. To get the secret key out
934 of the PSE, a special export tool has to be used.
938 Invokes the key generation process and the server will then inquire
939 on the generation parameters, like:
942 C: D (genkey (rsa (nbits 1024)))
945 The format of the key parameters which depends on the algorithm is of
950 (parameter_name_1 ....)
952 (parameter_name_n ....)))
954 If everything succeeds, the server returns the *public key* in a SPKI
955 like S-Expression like this:
962 Here is an example session:
966 C: D (genkey (rsa (nbits 1024)))
969 S: D (rsa (n 326487324683264) (e 10001)))
973 File: gnupg.info, Node: Agent IMPORT, Next: Agent EXPORT, Prev: Agent GENKEY, Up: Agent Protocol
975 2.6.4 Importing a Secret Key
976 ----------------------------
978 This operation is not yet supported by GpgAgent. Specialized tools are
981 There is no actual need because we can expect that secret keys
982 created by a 3rd party are stored on a smartcard. If we have generated
983 the key ourself, we do not need to import it.
986 File: gnupg.info, Node: Agent EXPORT, Next: Agent ISTRUSTED, Prev: Agent IMPORT, Up: Agent Protocol
988 2.6.5 Export a Secret Key
989 -------------------------
993 Should be done by an extra tool.
996 File: gnupg.info, Node: Agent ISTRUSTED, Next: Agent GET_PASSPHRASE, Prev: Agent EXPORT, Up: Agent Protocol
998 2.6.6 Importing a Root Certificate
999 ----------------------------------
1001 Actually we do not import a Root Cert but provide a way to validate any
1002 piece of data by storing its Hash along with a description and an
1003 identifier in the PSE. Here is the interface description:
1005 ISTRUSTED <fingerprint>
1007 Check whether the OpenPGP primary key or the X.509 certificate with
1008 the given fingerprint is an ultimately trusted key or a trusted Root CA
1009 certificate. The fingerprint should be given as a hexstring (without
1010 any blanks or colons or whatever in between) and may be left padded with
1011 00 in case of an MD5 fingerprint. GPGAgent will answer with:
1015 The key is in the table of trusted keys.
1017 ERR 304 (Not Trusted)
1019 The key is not in this table.
1021 Gpg needs the entire list of trusted keys to maintain the web of
1022 trust; the following command is therefore quite helpful:
1026 GpgAgent returns a list of trusted keys line by line:
1028 S: D 000000001234454556565656677878AF2F1ECCFF P
1029 S: D 340387563485634856435645634856438576457A P
1030 S: D FEDC6532453745367FD83474357495743757435D S
1033 The first item on a line is the hexified fingerprint where MD5
1034 fingerprints are `00' padded to the left and the second item is a flag
1035 to indicate the type of key (so that gpg is able to only take care of
1036 PGP keys). P = OpenPGP, S = S/MIME. A client should ignore the rest
1037 of the line, so that we can extend the format in the future.
1039 Finally a client should be able to mark a key as trusted:
1041 MARKTRUSTED FINGERPRINT "P"|"S"
1043 The server will then pop up a window to ask the user whether she
1044 really trusts this key. For this it will probably ask for a text to be
1045 displayed like this:
1047 S: INQUIRE TRUSTDESC
1048 C: D Do you trust the key with the fingerprint @FPR@
1049 C: D bla fasel blurb.
1053 Known sequences with the pattern @foo@ are replaced according to this
1057 Format the fingerprint according to gpg rules for a v3 keys.
1060 Format the fingerprint according to gpg rules for a v4 keys.
1063 Choose an appropriate format to format the fingerprint.
1066 Replaced by a single `@'
1069 File: gnupg.info, Node: Agent GET_PASSPHRASE, Next: Agent GET_CONFIRMATION, Prev: Agent ISTRUSTED, Up: Agent Protocol
1071 2.6.7 Ask for a passphrase
1072 --------------------------
1074 This function is usually used to ask for a passphrase to be used for
1075 conventional encryption, but may also be used by programs which need
1076 special handling of passphrases. This command uses a syntax which helps
1077 clients to use the agent with minimum effort.
1079 GET_PASSPHRASE [--data] [--check] [--no-ask] [--repeat[=N]] [--qualitybar] CACHE_ID [ERROR_MESSAGE PROMPT DESCRIPTION]
1081 CACHE_ID is expected to be a string used to identify a cached
1082 passphrase. Use a `X' to bypass the cache. With no other arguments
1083 the agent returns a cached passphrase or an error. By convention
1084 either the hexified fingerprint of the key shall be used for CACHE_ID
1085 or an arbitrary string prefixed with the name of the calling
1086 application and a colon: Like `gpg:somestring'.
1088 ERROR_MESSAGE is either a single `X' for no error message or a
1089 string to be shown as an error message like (e.g. "invalid
1090 passphrase"). Blanks must be percent escaped or replaced by `+''.
1092 PROMPT is either a single `X' for a default prompt or the text to be
1093 shown as the prompt. Blanks must be percent escaped or replaced by `+'.
1095 DESCRIPTION is a text shown above the entry field. Blanks must be
1096 percent escaped or replaced by `+'.
1098 The agent either returns with an error or with a OK followed by the
1099 hex encoded passphrase. Note that the length of the strings is
1100 implicitly limited by the maximum length of a command. If the option
1101 `--data' is used, the passphrase is not returned on the OK line but by
1102 regular data lines; this is the preferred method.
1104 If the option `--check' is used, the standard passphrase constraints
1105 checks are applied. A check is not done if the passphrase has been
1108 If the option `--no-ask' is used and the passphrase is not in the
1109 cache the user will not be asked to enter a passphrase but the error
1110 code `GPG_ERR_NO_DATA' is returned.
1112 If the option `--qualitybar' is used and a minimum passphrase length
1113 has been configured, a visual indication of the entered passphrase
1116 CLEAR_PASSPHRASE CACHE_ID
1118 may be used to invalidate the cache entry for a passphrase. The
1119 function returns with OK even when there is no cached passphrase.
1122 File: gnupg.info, Node: Agent GET_CONFIRMATION, Next: Agent HAVEKEY, Prev: Agent GET_PASSPHRASE, Up: Agent Protocol
1124 2.6.8 Ask for confirmation
1125 --------------------------
1127 This command may be used to ask for a simple confirmation by presenting
1128 a text and 2 buttons: Okay and Cancel.
1130 GET_CONFIRMATION DESCRIPTION
1132 DESCRIPTIONis displayed along with a Okay and Cancel button. Blanks
1133 must be percent escaped or replaced by `+'. A `X' may be used to
1134 display confirmation dialog with a default text.
1136 The agent either returns with an error or with a OK. Note, that the
1137 length of DESCRIPTION is implicitly limited by the maximum length of a
1141 File: gnupg.info, Node: Agent HAVEKEY, Next: Agent LEARN, Prev: Agent GET_CONFIRMATION, Up: Agent Protocol
1143 2.6.9 Check whether a key is available
1144 --------------------------------------
1146 This can be used to see whether a secret key is available. It does not
1147 return any information on whether the key is somehow protected.
1151 The agent answers either with OK or `No_Secret_Key' (208). The
1152 caller may want to check for other error codes as well. More than one
1153 keygrip may be given. In this case the command returns success if at
1154 least one of the keygrips corresponds to an available secret key.
1157 File: gnupg.info, Node: Agent LEARN, Next: Agent PASSWD, Prev: Agent HAVEKEY, Up: Agent Protocol
1159 2.6.10 Register a smartcard
1160 ---------------------------
1164 This command is used to register a smartcard. With the -send option
1165 given the certificates are send back.
1168 File: gnupg.info, Node: Agent PASSWD, Next: Agent UPDATESTARTUPTTY, Prev: Agent LEARN, Up: Agent Protocol
1170 2.6.11 Change a Passphrase
1171 --------------------------
1175 This command is used to interactively change the passphrase of the
1176 key identified by the hex string KEYGRIP.
1179 File: gnupg.info, Node: Agent UPDATESTARTUPTTY, Next: Agent GETEVENTCOUNTER, Prev: Agent PASSWD, Up: Agent Protocol
1181 2.6.12 Change the standard display
1182 ----------------------------------
1186 Set the startup TTY and X-DISPLAY variables to the values of this
1187 session. This command is useful to direct future pinentry invocations
1188 to another screen. It is only required because there is no way in the
1189 ssh-agent protocol to convey this information.
1192 File: gnupg.info, Node: Agent GETEVENTCOUNTER, Next: Agent GETINFO, Prev: Agent UPDATESTARTUPTTY, Up: Agent Protocol
1194 2.6.13 Get the Event Counters
1195 -----------------------------
1199 This function return one status line with the current values of the
1200 event counters. The event counters are useful to avoid polling by
1201 delaying a poll until something has changed. The values are decimal
1202 numbers in the range `0' to `UINT_MAX' and wrapping around to 0. The
1203 actual values should not be relied upon; they shall only be used to
1206 The currently defined counters are are:
1208 Incremented with any change of any of the other counters.
1211 Incremented for added or removed private keys.
1214 Incremented for changes of the card readers stati.
1217 File: gnupg.info, Node: Agent GETINFO, Next: Agent OPTION, Prev: Agent GETEVENTCOUNTER, Up: Agent Protocol
1219 2.6.14 Return information about the process
1220 -------------------------------------------
1222 This is a multipurpose function to return a variety of information.
1226 The value of WHAT specifies the kind of information returned:
1228 Return the version of the program.
1231 Return the process id of the process.
1234 Return the name of the socket used to connect the agent.
1237 Return the name of the socket used for SSH connections. If SSH
1238 support has not been enabled the error `GPG_ERR_NO_DATA' will be
1242 File: gnupg.info, Node: Agent OPTION, Prev: Agent GETINFO, Up: Agent Protocol
1244 2.6.15 Set options for the session
1245 ----------------------------------
1247 Here is a list of session options which are not yet described with
1248 other commands. The general syntax for an Assuan option is:
1255 This may be used to tell gpg-agent of which gpg-agent version the
1256 client is aware of. gpg-agent uses this information to enable
1257 features which might break older clients.
1260 Change the session's environment to be used for the Pinentry.
1267 Set envvar NAME to the empty string
1270 Set envvar NAME to the string VALUE.
1272 `use-cache-for-signing'
1273 See Assuan command `PKSIGN'.
1275 `allow-pinentry-notify'
1276 This does not need any value. It is used to enable the
1277 PINENTRY_LAUNCHED inquiry.
1281 File: gnupg.info, Node: Invoking GPG, Next: Invoking GPGSM, Prev: Invoking GPG-AGENT, Up: Top
1286 `gpg2' is the OpenPGP part of the GNU Privacy Guard (GnuPG). It is a
1287 tool to provide digital encryption and signing services using the
1288 OpenPGP standard. `gpg2' features complete key management and all bells
1289 and whistles you can expect from a decent OpenPGP implementation.
1291 In contrast to the standalone version `gpg', which is more suited
1292 for server and embedded platforms, this version is commonly installed
1293 under the name `gpg2' and more targeted to the desktop as it requires
1294 several other modules to be installed. The standalone version will be
1295 kept maintained and it is possible to install both versions on the same
1296 system. If you need to use different configuration files, you should
1297 make use of something like `gpg.conf-2' instead of just `gpg.conf'.
1299 Documentation for the old standard `gpg' is available as a man page
1300 and at *note GnuPG 1: (gpg)Top.
1302 *Note Option Index::, for an index to `gpg2''s commands and options.
1306 * GPG Commands:: List of all commands.
1307 * GPG Options:: List of all options.
1308 * GPG Configuration:: Configuration files.
1309 * GPG Examples:: Some usage examples.
1311 Developer information:
1312 * Unattended Usage of GPG:: Using `gpg' from other programs.
1315 File: gnupg.info, Node: GPG Commands, Next: GPG Options, Up: Invoking GPG
1320 Commands are not distinguished from options except for the fact that
1321 only one command is allowed.
1323 `gpg2' may be run with no commands, in which case it will perform a
1324 reasonable action depending on the type of file it is given as input
1325 (an encrypted message is decrypted, a signature is verified, a file
1326 containing keys is listed).
1328 Please remember that option as well as command parsing stops as soon
1329 as a non-option is encountered, you can explicitly stop parsing by
1330 using the special option `--'.
1334 * General GPG Commands:: Commands not specific to the functionality.
1335 * Operational GPG Commands:: Commands to select the type of operation.
1336 * OpenPGP Key Management:: How to manage your keys.
1339 File: gnupg.info, Node: General GPG Commands, Next: Operational GPG Commands, Up: GPG Commands
1341 3.1.1 Commands not specific to the function
1342 -------------------------------------------
1345 Print the program version and licensing information. Note that you
1346 cannot abbreviate this command.
1350 Print a usage message summarizing the most useful command line
1351 options. Note that you cannot abbreviate this command.
1354 Print warranty information.
1357 Print a list of all available options and commands. Note that you
1358 cannot abbreviate this command.
1361 File: gnupg.info, Node: Operational GPG Commands, Next: OpenPGP Key Management, Prev: General GPG Commands, Up: GPG Commands
1363 3.1.2 Commands to select the type of operation
1364 ----------------------------------------------
1368 Make a signature. This command may be combined with `--encrypt'
1369 (for a signed and encrypted message), `--symmetric' (for a signed
1370 and symmetrically encrypted message), or `--encrypt' and
1371 `--symmetric' together (for a signed message that may be decrypted
1372 via a secret key or a passphrase). The key to be used for signing
1373 is chosen by default or can be set with the `--local-user' and
1374 `--default-key' options.
1377 Make a clear text signature. The content in a clear text
1378 signature is readable without any special software. OpenPGP
1379 software is only needed to verify the signature. Clear text
1380 signatures may modify end-of-line whitespace for platform
1381 independence and are not intended to be reversible. The key to be
1382 used for signing is chosen by default or can be set with the
1383 `--local-user' and `--default-key' options.
1387 Make a detached signature.
1391 Encrypt data. This option may be combined with `--sign' (for a
1392 signed and encrypted message), `--symmetric' (for a message that
1393 may be decrypted via a secret key or a passphrase), or `--sign'
1394 and `--symmetric' together (for a signed message that may be
1395 decrypted via a secret key or a passphrase).
1399 Encrypt with a symmetric cipher using a passphrase. The default
1400 symmetric cipher used is CAST5, but may be chosen with the
1401 `--cipher-algo' option. This option may be combined with `--sign'
1402 (for a signed and symmetrically encrypted message), `--encrypt'
1403 (for a message that may be decrypted via a secret key or a
1404 passphrase), or `--sign' and `--encrypt' together (for a signed
1405 message that may be decrypted via a secret key or a passphrase).
1408 Store only (make a simple RFC1991 literal data packet).
1412 Decrypt the file given on the command line (or STDIN if no file is
1413 specified) and write it to STDOUT (or the file specified with
1414 `--output'). If the decrypted file is signed, the signature is also
1415 verified. This command differs from the default operation, as it
1416 never writes to the filename which is included in the file and it
1417 rejects files which don't begin with an encrypted message.
1420 Assume that the first argument is a signed file or a detached
1421 signature and verify it without generating any output. With no
1422 arguments, the signature packet is read from STDIN. If only a
1423 sigfile is given, it may be a complete signature or a detached
1424 signature, in which case the signed stuff is expected in a file
1425 without the ".sig" or ".asc" extension. With more than 1
1426 argument, the first should be a detached signature and the
1427 remaining files are the signed stuff. To read the signed stuff
1428 from STDIN, use `-' as the second filename. For security reasons
1429 a detached signature cannot read the signed material from STDIN
1430 without denoting it in the above way.
1433 This modifies certain other commands to accept multiple files for
1434 processing on the command line or read from STDIN with each
1435 filename on a separate line. This allows for many files to be
1436 processed at once. `--multifile' may currently be used along with
1437 `--verify', `--encrypt', and `--decrypt'. Note that `--multifile
1438 --verify' may not be used with detached signatures.
1441 Identical to `--multifile --verify'.
1444 Identical to `--multifile --encrypt'.
1447 Identical to `--multifile --decrypt'.
1451 `--list-public-keys'
1452 List all keys from the public keyrings, or just the keys given on
1455 Avoid using the output of this command in scripts or other
1456 programs as it is likely to change as GnuPG changes. See
1457 `--with-colons' for a machine-parseable key listing command that
1458 is appropriate for use in scripts and other programs.
1460 `--list-secret-keys'
1462 List all keys from the secret keyrings, or just the ones given on
1463 the command line. A `#' after the letters `sec' means that the
1464 secret key is not usable (for example, if it was created via
1465 `--export-secret-subkeys').
1468 Same as `--list-keys', but the signatures are listed too. This
1469 command has the same effect as using `--list-keys' with
1472 For each signature listed, there are several flags in between the
1473 "sig" tag and keyid. These flags give additional information about
1474 each signature. From left to right, they are the numbers 1-3 for
1475 certificate check level (see `--ask-cert-level'), "L" for a local
1476 or non-exportable signature (see `--lsign-key'), "R" for a
1477 nonRevocable signature (see the `--edit-key' command "nrsign"),
1478 "P" for a signature that contains a policy URL (see
1479 `--cert-policy-url'), "N" for a signature that contains a notation
1480 (see `--cert-notation'), "X" for an eXpired signature (see
1481 `--ask-cert-expire'), and the numbers 1-9 or "T" for 10 and above
1482 to indicate trust signature levels (see the `--edit-key' command
1486 Same as `--list-sigs', but the signatures are verified. Note that
1487 for performance reasons the revocation status of a signing key is
1488 not shown. This command has the same effect as using
1489 `--list-keys' with `--with-sig-check'.
1491 The status of the verification is indicated by a flag directly
1492 following the "sig" tag (and thus before the flags described above
1493 for `--list-sigs'). A "!" indicates that the signature has been
1494 successfully verified, a "-" denotes a bad signature and a "%" is
1495 used if an error occurred while checking the signature (e.g. a non
1496 supported algorithm).
1499 Locate the keys given as arguments. This command basically uses
1500 the same algorithm as used when locating keys for encryption or
1501 signing and may thus be used to see what keys `gpg2' might use. In
1502 particular external methods as defined by `--auto-key-locate' may
1503 be used to locate a key. Only public keys are listed.
1506 List all keys (or the specified ones) along with their
1507 fingerprints. This is the same output as `--list-keys' but with
1508 the additional output of a line with the fingerprint. May also be
1509 combined with `--list-sigs' or `--check-sigs'. If this command is
1510 given twice, the fingerprints of all secondary keys are listed too.
1513 List only the sequence of packets. This is mainly useful for
1517 Present a menu to work with a smartcard. The subcommand "help"
1518 provides an overview on available commands. For a detailed
1519 description, please see the Card HOWTO at
1520 http://www.gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
1523 Show the content of the smart card.
1526 Present a menu to allow changing the PIN of a smartcard. This
1527 functionality is also available as the subcommand "passwd" with the
1528 `--card-edit' command.
1530 `--delete-key `name''
1531 Remove key from the public keyring. In batch mode either `--yes' is
1532 required or the key must be specified by fingerprint. This is a
1533 safeguard against accidental deletion of multiple keys.
1535 `--delete-secret-key `name''
1536 Remove key from the secret and public keyring. In batch mode the
1537 key must be specified by fingerprint.
1539 `--delete-secret-and-public-key `name''
1540 Same as `--delete-key', but if a secret key exists, it will be
1541 removed first. In batch mode the key must be specified by
1545 Either export all keys from all keyrings (default keyrings and
1546 those registered via option `--keyring'), or if at least one name
1547 is given, those of the given name. The new keyring is written to
1548 STDOUT or to the file given with option `--output'. Use together
1549 with `--armor' to mail those keys.
1551 `--send-keys `key IDs''
1552 Similar to `--export' but sends the keys to a keyserver.
1553 Fingerprints may be used instead of key IDs. Option `--keyserver'
1554 must be used to give the name of this keyserver. Don't send your
1555 complete keyring to a keyserver -- select only those keys which
1556 are new or changed by you. If no key IDs are given, `gpg' does
1559 `--export-secret-keys'
1560 `--export-secret-subkeys'
1561 Same as `--export', but exports the secret keys instead. This is
1562 normally not very useful and a security risk. The second form of
1563 the command has the special property to render the secret part of
1564 the primary key useless; this is a GNU extension to OpenPGP and
1565 other implementations can not be expected to successfully import
1566 such a key. See the option `--simple-sk-checksum' if you want to
1567 import such an exported key with an older OpenPGP implementation.
1571 Import/merge keys. This adds the given keys to the keyring. The
1572 fast version is currently just a synonym.
1574 There are a few other options which control how this command works.
1575 Most notable here is the `--import-options merge-only' option
1576 which does not insert new keys but does only the merging of new
1577 signatures, user-IDs and subkeys.
1579 `--recv-keys `key IDs''
1580 Import the keys with the given key IDs from a keyserver. Option
1581 `--keyserver' must be used to give the name of this keyserver.
1584 Request updates from a keyserver for keys that already exist on the
1585 local keyring. This is useful for updating a key with the latest
1586 signatures, user IDs, etc. Calling this with no arguments will
1587 refresh the entire keyring. Option `--keyserver' must be used to
1588 give the name of the keyserver for all keys that do not have
1589 preferred keyservers set (see `--keyserver-options
1590 honor-keyserver-url').
1592 `--search-keys `names''
1593 Search the keyserver for the given names. Multiple names given
1594 here will be joined together to create the search string for the
1595 keyserver. Option `--keyserver' must be used to give the name of
1596 this keyserver. Keyservers that support different search methods
1597 allow using the syntax specified in "How to specify a user ID"
1598 below. Note that different keyserver types support different
1599 search methods. Currently only LDAP supports them all.
1601 `--fetch-keys `URIs''
1602 Retrieve keys located at the specified URIs. Note that different
1603 installations of GnuPG may support different protocols (HTTP, FTP,
1607 Do trust database maintenance. This command iterates over all keys
1608 and builds the Web of Trust. This is an interactive command
1609 because it may have to ask for the "ownertrust" values for keys.
1610 The user has to give an estimation of how far she trusts the owner
1611 of the displayed key to correctly certify (sign) other keys. GnuPG
1612 only asks for the ownertrust value if it has not yet been assigned
1613 to a key. Using the `--edit-key' menu, the assigned value can be
1614 changed at any time.
1617 Do trust database maintenance without user interaction. From time
1618 to time the trust database must be updated so that expired keys or
1619 signatures and the resulting changes in the Web of Trust can be
1620 tracked. Normally, GnuPG will calculate when this is required and
1621 do it automatically unless `--no-auto-check-trustdb' is set. This
1622 command can be used to force a trust database check at any time.
1623 The processing is identical to that of `--update-trustdb' but it
1624 skips keys with a not yet defined "ownertrust".
1626 For use with cron jobs, this command can be used together with
1627 `--batch' in which case the trust database check is done only if a
1628 check is needed. To force a run even in batch mode add the option
1631 `--export-ownertrust'
1632 Send the ownertrust values to STDOUT. This is useful for backup
1633 purposes as these values are the only ones which can't be
1634 re-created from a corrupted trustdb. Example:
1635 gpg2 --export-ownertrust > otrust.txt
1637 `--import-ownertrust'
1638 Update the trustdb with the ownertrust values stored in `files' (or
1639 STDIN if not given); existing values will be overwritten. In case
1640 of a severely damaged trustdb and if you have a recent backup of
1641 the ownertrust values (e.g. in the file `otrust.txt', you may
1642 re-create the trustdb using these commands:
1645 gpg2 --import-ownertrust < otrust.txt
1647 `--rebuild-keydb-caches'
1648 When updating from version 1.0.6 to 1.0.7 this command should be
1649 used to create signature caches in the keyring. It might be handy
1650 in other situations too.
1654 Print message digest of algorithm ALGO for all given files or
1655 STDIN. With the second form (or a deprecated "*" as algo) digests
1656 for all available algorithms are printed.
1658 `--gen-random `0|1|2' `count''
1659 Emit COUNT random bytes of the given quality level 0, 1 or 2. If
1660 COUNT is not given or zero, an endless sequence of random bytes
1661 will be emitted. If used with `--armor' the output will be base64
1662 encoded. PLEASE, don't use this command unless you know what you
1663 are doing; it may remove precious entropy from the system!
1665 `--gen-prime `mode' `bits''
1666 Use the source, Luke :-). The output format is still subject to
1672 Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
1673 This is a GnuPG extension to OpenPGP and in general not very
1678 File: gnupg.info, Node: OpenPGP Key Management, Prev: Operational GPG Commands, Up: GPG Commands
1680 3.1.3 How to manage your keys
1681 -----------------------------
1683 This section explains the main commands for key management
1686 Generate a new key pair. This command is normally only used
1689 There is an experimental feature which allows you to create keys in
1690 batch mode. See the file `doc/DETAILS' in the source distribution
1693 `--gen-revoke `name''
1694 Generate a revocation certificate for the complete key. To revoke
1695 a subkey or a signature, use the `--edit' command.
1697 `--desig-revoke `name''
1698 Generate a designated revocation certificate for a key. This
1699 allows a user (with the permission of the keyholder) to revoke
1703 Present a menu which enables you to do most of the key management
1704 related tasks. It expects the specification of a key on the
1708 Toggle selection of user ID or photographic user ID with
1709 index `n'. Use `*' to select all and `0' to deselect all.
1712 Toggle selection of subkey with index `n'. Use `*' to
1713 select all and `0' to deselect all.
1716 Make a signature on key of user `name' If the key is not yet
1717 signed by the default user (or the users given with -u), the
1718 program displays the information of the key again, together
1719 with its fingerprint and asks whether it should be signed.
1720 This question is repeated for all users specified with -u.
1723 Same as "sign" but the signature is marked as non-exportable
1724 and will therefore never be used by others. This may be
1725 used to make keys valid only in the local environment.
1728 Same as "sign" but the signature is marked as non-revocable
1729 and can therefore never be revoked.
1732 Make a trust signature. This is a signature that combines the
1733 notions of certification (like a regular signature), and
1734 trust (like the "trust" command). It is generally only
1735 useful in distinct communities or groups.
1737 Note that "l" (for local / non-exportable), "nr" (for
1738 non-revocable, and "t" (for trust) may be freely mixed and
1739 prefixed to "sign" to create a signature of any type desired.
1742 Delete a signature. Note that it is not possible to retract a
1743 signature, once it has been send to the public (i.e. to a
1744 keyserver). In that case you better use `revsig'.
1747 Revoke a signature. For every signature which has been
1748 generated by one of the secret keys, GnuPG asks whether a
1749 revocation certificate should be generated.
1752 Check the signatures on all selected user IDs.
1755 Create an additional user ID.
1758 Create a photographic user ID. This will prompt for a JPEG
1759 file that will be embedded into the user ID. Note that a
1760 very large JPEG will make for a very large key. Also note
1761 that some programs will display your JPEG unchanged
1762 (GnuPG), and some programs will scale it to fit in a dialog
1766 Display the selected photographic user ID.
1769 Delete a user ID or photographic user ID. Note that it is not
1770 possible to retract a user id, once it has been send to the
1771 public (i.e. to a keyserver). In that case you better use
1775 Revoke a user ID or photographic user ID.
1778 Flag the current user id as the primary one, removes the
1779 primary user id flag from all other user ids and sets the
1780 timestamp of all affected self-signatures one second ahead.
1781 Note that setting a photo user ID as primary makes it
1782 primary over other photo user IDs, and setting a regular
1783 user ID as primary makes it primary over other regular user
1787 Set a preferred keyserver for the specified user ID(s). This
1788 allows other users to know where you prefer they get your
1789 key from. See `--keyserver-options honor-keyserver-url' for
1790 more on how this works. Setting a value of "none" removes
1791 an existing preferred keyserver.
1794 Set a name=value notation for the specified user ID(s). See
1795 `--cert-notation' for more on how this works. Setting a value
1796 of "none" removes all notations, setting a notation
1797 prefixed with a minus sign (-) removes that notation, and
1798 setting a notation name (without the =value) prefixed with
1799 a minus sign removes all notations with that name.
1802 List preferences from the selected user ID. This shows the
1803 actual preferences, without including any implied
1807 More verbose preferences listing for the selected user ID.
1808 This shows the preferences in effect by including the
1809 implied preferences of 3DES (cipher), SHA-1 (digest), and
1810 Uncompressed (compression) if they are not already included
1811 in the preference list. In addition, the preferred
1812 keyserver and signature notations (if any) are shown.
1815 Set the list of user ID preferences to `string' for all (or
1816 just the selected) user IDs. Calling setpref with no
1817 arguments sets the preference list to the default (either
1818 built-in or set via `--default-preference-list'), and
1819 calling setpref with "none" as the argument sets an empty
1820 preference list. Use `gpg2 --version' to get a list of
1821 available algorithms. Note that while you can change the
1822 preferences on an attribute user ID (aka "photo ID"), GnuPG
1823 does not select keys via attribute user IDs so these
1824 preferences will not be used by GnuPG.
1826 When setting preferences, you should list the algorithms in
1827 the order which you'd like to see them used by someone else
1828 when encrypting a message to your key. If you don't
1829 include 3DES, it will be automatically added at the end.
1830 Note that there are many factors that go into choosing an
1831 algorithm (for example, your key may not be the only
1832 recipient), and so the remote OpenPGP application being used
1833 to send to you may or may not follow your exact chosen
1834 order for a given message. It will, however, only choose
1835 an algorithm that is present on the preference list of
1836 every recipient key. See also the INTEROPERABILITY WITH
1837 OTHER OPENPGP PROGRAMS section below.
1840 Add a subkey to this key.
1843 Generate a subkey on a card and add it to this key.
1846 Transfer the selected secret subkey (or the primary key if no
1847 subkey has been selected) to a smartcard. The secret key in
1848 the keyring will be replaced by a stub if the key could be
1849 stored successfully on the card and you use the save
1850 command later. Only certain key types may be transferred to
1851 the card. A sub menu allows you to select on what card to
1852 store the key. Note that it is not possible to get that key
1853 back from the card - if the card gets broken your secret
1854 key will be lost unless you have a backup somewhere.
1857 Restore the given file to a card. This command may be used to
1858 restore a backup key (as generated during card
1859 initialization) to a new card. In almost all cases this
1860 will be the encryption key. You should use this command
1861 only with the corresponding public key and make sure that the
1862 file given as argument is indeed the backup to restore. You
1863 should then select 2 to restore as encryption key. You
1864 will first be asked to enter the passphrase of the backup
1865 key and then for the Admin PIN of the card.
1868 Remove a subkey (secondart key). Note that it is not possible
1869 to retract a subkey, once it has been send to the public
1870 (i.e. to a keyserver). In that case you better use
1877 Change the key or subkey expiration time. If a subkey is
1878 selected, the expiration time of this subkey will be
1879 changed. With no selection, the key expiration of the
1880 primary key is changed.
1883 Change the owner trust value for the key. This updates the
1884 trust-db immediately and no save is required.
1888 Disable or enable an entire key. A disabled key can not
1889 normally be used for encryption.
1892 Add a designated revoker to the key. This takes one optional
1893 argument: "sensitive". If a designated revoker is marked as
1894 sensitive, it will not be exported by default (see
1898 Change the passphrase of the secret key.
1901 Toggle between public and secret key listing.
1904 Compact (by removing all signatures except the selfsig) any
1905 user ID that is no longer usable (e.g. revoked, or
1906 expired). Then, remove any signatures that are not usable
1907 by the trust calculations. Specifically, this removes any
1908 signature that does not validate, any signature that is
1909 superseded by a later signature, revoked signatures, and
1910 signatures issued by keys that are not present on the keyring.
1913 Make the key as small as possible. This removes all
1914 signatures from each user ID except for the most recent
1918 Add cross-certification signatures to signing subkeys that
1919 may not currently have them. Cross-certification signatures
1920 protect against a subtle attack against signing subkeys. See
1921 `--require-cross-certification'. All new keys generated have
1922 this signature by default, so this option is only useful to
1923 bring older keys up to date.
1926 Save all changes to the key rings and quit.
1929 Quit the program without updating the key rings.
1931 The listing shows you the key with its secondary keys and all user
1932 ids. The primary user id is indicated by a dot, and selected keys
1933 or user ids are indicated by an asterisk. The trust value is
1934 displayed with the primary key: the first is the assigned owner
1935 trust and the second is the calculated trust value. Letters are
1936 used for the values:
1939 No ownertrust assigned / not yet calculated.
1942 Trust calculation has failed; probably due to an expired
1946 Not enough information for calculation.
1949 Never trust this key.
1962 Signs a public key with your secret key. This is a shortcut
1963 version of the subcommand "sign" from `--edit'.
1965 `--lsign-key `name''
1966 Signs a public key with your secret key but marks it as
1967 non-exportable. This is a shortcut version of the subcommand
1968 "lsign" from `--edit-key'.
1971 Change the passphrase of the secret key belonging to the
1972 certificate specified as USER_ID. This is a shortcut for the
1973 sub-command `passwd' of the edit key menu.
1977 File: gnupg.info, Node: GPG Options, Next: GPG Configuration, Prev: GPG Commands, Up: Invoking GPG
1982 `gpg2' features a bunch of options to control the exact behaviour and
1983 to change the default configuration.
1987 * GPG Configuration Options:: How to change the configuration.
1988 * GPG Key related Options:: Key related options.
1989 * GPG Input and Output:: Input and Output.
1990 * OpenPGP Options:: OpenPGP protocol specific options.
1991 * GPG Esoteric Options:: Doing things one usually don't want to do.
1993 Long options can be put in an options file (default
1994 "~/.gnupg/gpg.conf"). Short option names will not work - for example,
1995 "armor" is a valid option for the options file, while "a" is not. Do not
1996 write the 2 dashes, but simply the name of the option and any required
1997 arguments. Lines with a hash ('#') as the first non-white-space
1998 character are ignored. Commands may be put in this file too, but that is
1999 not generally useful as the command will execute automatically with
2000 every execution of gpg.
2002 Please remember that option parsing stops as soon as a non-option is
2003 encountered, you can explicitly stop parsing by using the special option
2007 File: gnupg.info, Node: GPG Configuration Options, Next: GPG Key related Options, Up: GPG Options
2009 3.2.1 How to change the configuration
2010 -------------------------------------
2012 These options are used to change the configuration and are usually found
2015 `--default-key NAME'
2016 Use NAME as the default key to sign with. If this option is not
2017 used, the default key is the first key found in the secret keyring.
2018 Note that `-u' or `--local-user' overrides this option.
2020 `--default-recipient NAME'
2021 Use NAME as default recipient if option `--recipient' is not used
2022 and don't ask if this is a valid one. NAME must be non-empty.
2024 `--default-recipient-self'
2025 Use the default key as default recipient if option `--recipient'
2026 is not used and don't ask if this is a valid one. The default key
2027 is the first one from the secret keyring or the one set with
2030 `--no-default-recipient'
2031 Reset `--default-recipient' and `--default-recipient-self'.
2034 Give more information during processing. If used twice, the input
2035 data is listed in detail.
2038 Reset verbose level to 0.
2041 Try to be as quiet as possible.
2045 Use batch mode. Never ask, do not allow interactive commands.
2046 `--no-batch' disables this option. Note that even with a filename
2047 given on the command line, gpg might still need to read from STDIN
2048 (in particular if gpg figures that the input is a detached
2049 signature and no data file has been specified). Thus if you do
2050 not want to feed data via STDIN, you should connect STDIN to
2054 Make sure that the TTY (terminal) is never used for any output.
2055 This option is needed in some cases because GnuPG sometimes prints
2056 warnings to the TTY even if `--batch' is used.
2059 Assume "yes" on most questions.
2062 Assume "no" on most questions.
2064 `--list-options `parameters''
2065 This is a space or comma delimited string that gives options used
2066 when listing keys and signatures (that is, `--list-keys',
2067 `--list-sigs', `--list-public-keys', `--list-secret-keys', and the
2068 `--edit-key' functions). Options can be prepended with a `no-'
2069 (after the two dashes) to give the opposite meaning. The options
2073 Causes `--list-keys', `--list-sigs', `--list-public-keys',
2074 and `--list-secret-keys' to display any photo IDs attached
2075 to the key. Defaults to no. See also `--photo-viewer'.
2076 Does not work with `--with-colons': see `--attribute-fd'
2077 for the appropriate way to get photo data for scripts and
2081 Show policy URLs in the `--list-sigs' or `--check-sigs'
2082 listings. Defaults to no.
2087 Show all, IETF standard, or user-defined signature notations
2088 in the `--list-sigs' or `--check-sigs' listings. Defaults
2092 Show any preferred keyserver URL in the `--list-sigs' or
2093 `--check-sigs' listings. Defaults to no.
2096 Display the calculated validity of user IDs during key
2097 listings. Defaults to no.
2100 Show revoked and expired user IDs in key listings. Defaults
2103 show-unusable-subkeys
2104 Show revoked and expired subkeys in key listings. Defaults to
2108 Display the keyring name at the head of key listings to show
2109 which keyring a given key resides on. Defaults to no.
2112 Show signature expiration dates (if any) during `--list-sigs'
2113 or `--check-sigs' listings. Defaults to no.
2116 Include signature subpackets in the key listing. This option
2117 can take an optional argument list of the subpackets to
2118 list. If no argument is passed, list all subpackets.
2119 Defaults to no. This option is only meaningful when using
2120 `--with-colons' along with `--list-sigs' or `--check-sigs'.
2123 `--verify-options `parameters''
2124 This is a space or comma delimited string that gives options used
2125 when verifying signatures. Options can be prepended with a `no-'
2126 to give the opposite meaning. The options are:
2129 Display any photo IDs present on the key that issued the
2130 signature. Defaults to no. See also `--photo-viewer'.
2133 Show policy URLs in the signature being verified. Defaults to
2139 Show all, IETF standard, or user-defined signature notations
2140 in the signature being verified. Defaults to IETF standard.
2143 Show any preferred keyserver URL in the signature being
2144 verified. Defaults to no.
2147 Display the calculated validity of the user IDs on the key
2148 that issued the signature. Defaults to no.
2151 Show revoked and expired user IDs during signature
2152 verification. Defaults to no.
2154 show-primary-uid-only
2155 Show only the primary user ID during signature verification.
2156 That is all the AKA lines as well as photo Ids are not
2157 shown with the signature verification status.
2160 Enable PKA lookups to verify sender addresses. Note that PKA
2161 is based on DNS, and so enabling this option may disclose
2162 information on when and what signatures are verified or to
2163 whom data is encrypted. This is similar to the "web bug"
2164 described for the auto-key-retrieve feature.
2167 Raise the trust in a signature to full if the signature
2168 passes PKA validation. This option is only meaningful if
2173 Enable hash truncation for all DSA keys even for old DSA Keys up to
2174 1024 bit. This is also the default with `--openpgp'. Note that
2175 older versions of GnuPG also required this flag to allow the
2176 generation of DSA larger than 1024 bit.
2178 `--photo-viewer `string''
2179 This is the command line that should be run to view a photo ID.
2180 "%i" will be expanded to a filename containing the photo. "%I"
2181 does the same, except the file will not be deleted once the viewer
2182 exits. Other flags are "%k" for the key ID, "%K" for the long key
2183 ID, "%f" for the key fingerprint, "%t" for the extension of the
2184 image type (e.g. "jpg"), "%T" for the MIME type of the image (e.g.
2185 "image/jpeg"), "%v" for the single-character calculated validity
2186 of the image being viewed (e.g. "f"), "%V" for the calculated
2187 validity as a string (e.g. "full"), and "%%" for an actual
2188 percent sign. If neither %i or %I are present, then the photo will
2189 be supplied to the viewer on standard input.
2191 The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
2192 STDIN". Note that if your image viewer program is not secure, then
2193 executing it from GnuPG does not make it secure.
2195 `--exec-path `string''
2196 Sets a list of directories to search for photo viewers and
2197 keyserver helpers. If not provided, keyserver helpers use the
2198 compiled-in default directory, and photo viewers use the $PATH
2199 environment variable. Note, that on W32 system this value is
2200 ignored when searching for keyserver helpers.
2203 Add `file' to the current list of keyrings. If `file' begins with
2204 a tilde and a slash, these are replaced by the $HOME directory. If
2205 the filename does not contain a slash, it is assumed to be in the
2206 GnuPG home directory ("~/.gnupg" if `--homedir' or $GNUPGHOME is
2209 Note that this adds a keyring to the current list. If the intent
2210 is to use the specified keyring alone, use `--keyring' along with
2211 `--no-default-keyring'.
2213 `--secret-keyring `file''
2214 Same as `--keyring' but for the secret keyrings.
2216 `--primary-keyring `file''
2217 Designate `file' as the primary public keyring. This means that
2218 newly imported keys (via `--import' or keyserver `--recv-from')
2219 will go to this keyring.
2221 `--trustdb-name `file''
2222 Use `file' instead of the default trustdb. If `file' begins with a
2223 tilde and a slash, these are replaced by the $HOME directory. If
2224 the filename does not contain a slash, it is assumed to be in the
2225 GnuPG home directory (`~/.gnupg' if `--homedir' or $GNUPGHOME is
2229 Set the name of the home directory to DIR. If this option is not
2230 used, the home directory defaults to `~/.gnupg'. It is only
2231 recognized when given on the command line. It also overrides any
2232 home directory stated through the environment variable `GNUPGHOME'
2233 or (on W32 systems) by means of the Registry entry
2234 HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
2236 `--display-charset `name''
2237 Set the name of the native character set. This is used to convert
2238 some informational strings like user IDs to the proper UTF-8
2239 encoding. Note that this has nothing to do with the character set
2240 of data to be encrypted or signed; GnuPG does not recode
2241 user-supplied data. If this option is not used, the default
2242 character set is determined from the current locale. A verbosity
2243 level of 3 shows the chosen set. Valid values for `name' are:
2246 This is the Latin 1 set.
2252 This is currently an alias for the Latin 1 set.
2255 The usual Russian set (rfc1489).
2258 Bypass all translations and assume that the OS uses native
2263 Assume that command line arguments are given as UTF8 strings. The
2264 default (`--no-utf8-strings') is to assume that arguments are
2265 encoded in the character set as specified by `--display-charset'.
2266 These options affect all following arguments. Both options may be
2267 used multiple times.
2270 Read options from `file' and do not try to read them from the
2271 default options file in the homedir (see `--homedir'). This option
2272 is ignored if used in an options file.
2275 Shortcut for `--options /dev/null'. This option is detected before
2276 an attempt to open an option file. Using this option will also
2277 prevent the creation of a `~/.gnupg' homedir.
2280 `--compress-level `n''
2281 `--bzip2-compress-level `n''
2282 Set compression level to `n' for the ZIP and ZLIB compression
2283 algorithms. The default is to use the default compression level of
2284 zlib (normally 6). `--bzip2-compress-level' sets the compression
2285 level for the BZIP2 compression algorithm (defaulting to 6 as
2286 well). This is a different option from `--compress-level' since
2287 BZIP2 uses a significant amount of memory for each additional
2288 compression level. `-z' sets both. A value of 0 for `n' disables
2291 `--bzip2-decompress-lowmem'
2292 Use a different decompression method for BZIP2 compressed files.
2293 This alternate method uses a bit more than half the memory, but
2294 also runs at half the speed. This is useful under extreme low
2295 memory circumstances when the file was originally compressed at a
2296 high `--bzip2-compress-level'.
2298 `--mangle-dos-filenames'
2299 `--no-mangle-dos-filenames'
2300 Older version of Windows cannot handle filenames with more than one
2301 dot. `--mangle-dos-filenames' causes GnuPG to replace (rather than
2302 add to) the extension of an output filename to avoid this problem.
2303 This option is off by default and has no effect on non-Windows
2307 `--no-ask-cert-level'
2308 When making a key signature, prompt for a certification level. If
2309 this option is not specified, the certification level used is set
2310 via `--default-cert-level'. See `--default-cert-level' for
2311 information on the specific levels and how they are used.
2312 `--no-ask-cert-level' disables this option. This option defaults
2315 `--default-cert-level `n''
2316 The default to use for the check level when signing a key.
2318 0 means you make no particular claim as to how carefully you
2321 1 means you believe the key is owned by the person who claims to
2322 own it but you could not, or did not verify the key at all. This is
2323 useful for a "persona" verification, where you sign the key of a
2326 2 means you did casual verification of the key. For example, this
2327 could mean that you verified the key fingerprint and checked the
2328 user ID on the key against a photo ID.
2330 3 means you did extensive verification of the key. For example,
2331 this could mean that you verified the key fingerprint with the
2332 owner of the key in person, and that you checked, by means of a
2333 hard to forge document with a photo ID (such as a passport) that
2334 the name of the key owner matches the name in the user ID on the
2335 key, and finally that you verified (by exchange of email) that the
2336 email address on the key belongs to the key owner.
2338 Note that the examples given above for levels 2 and 3 are just
2339 that: examples. In the end, it is up to you to decide just what
2340 "casual" and "extensive" mean to you.
2342 This option defaults to 0 (no particular claim).
2345 When building the trust database, treat any signatures with a
2346 certification level below this as invalid. Defaults to 2, which
2347 disregards level 1 signatures. Note that level 0 "no particular
2348 claim" signatures are always accepted.
2350 `--trusted-key `long key ID''
2351 Assume that the specified key (which must be given as a full 8
2352 byte key ID) is as trustworthy as one of your own secret keys.
2353 This option is useful if you don't want to keep your secret keys
2354 (or one of them) online but still want to be able to check the
2355 validity of a given recipient's or signator's key.
2357 `--trust-model `pgp|classic|direct|always|auto''
2358 Set what trust model GnuPG should follow. The models are:
2361 This is the Web of Trust combined with trust signatures as
2362 used in PGP 5.x and later. This is the default trust model
2363 when creating a new trust database.
2366 This is the standard Web of Trust as used in PGP 2.x and
2370 Key validity is set directly by the user and not calculated
2371 via the Web of Trust.
2374 Skip key validation and assume that used keys are always fully
2375 trusted. You generally won't use this unless you are using
2376 some external validation scheme. This option also
2377 suppresses the "[uncertain]" tag printed with signature
2378 checks when there is no evidence that the user ID is bound
2382 Select the trust model depending on whatever the internal
2383 trust database says. This is the default model if such a
2384 database already exists.
2386 `--auto-key-locate `parameters''
2387 `--no-auto-key-locate'
2388 GnuPG can automatically locate and retrieve keys as needed using
2389 this option. This happens when encrypting to an email address (in
2390 the "user@example.com" form), and there are no user@example.com
2391 keys on the local keyring. This option takes any number of the
2392 following mechanisms, in the order they are to be tried:
2395 Locate a key using DNS CERT, as specified in rfc4398.
2398 Locate a key using DNS PKA.
2401 Using DNS Service Discovery, check the domain in question for
2402 any LDAP keyservers to use. If this fails, attempt to
2403 locate the key using the PGP Universal method of checking
2404 `ldap://keys.(thedomain)'.
2407 Locate a key using whatever keyserver is defined using the
2408 `--keyserver' option.
2411 In addition, a keyserver URL as used in the `--keyserver'
2412 option may be used here to query that particular keyserver.
2415 Locate the key using the local keyrings. This mechanism
2416 allows to select the order a local key lookup is done.
2417 Thus using `--auto-key-locate local' is identical to
2418 `--no-auto-key-locate'.
2421 This flag disables the standard local key lookup, done before
2422 any of the mechanisms defined by the `--auto-key-locate'
2423 are tried. The position of this mechanism in the list does
2424 not matter. It is not required if `local' is also used.
2427 `--keyid-format `short|0xshort|long|0xlong''
2428 Select how to display key IDs. "short" is the traditional
2429 8-character key ID. "long" is the more accurate (but less
2430 convenient) 16-character key ID. Add an "0x" to either to include
2431 an "0x" at the beginning of the key ID, as in 0x99242560. Note
2432 that this option is ignored if the option -with-colons is used.
2434 `--keyserver `name''
2435 Use `name' as your keyserver. This is the server that
2436 `--recv-keys', `--send-keys', and `--search-keys' will communicate
2437 with to receive keys from, send keys to, and search for keys on.
2438 The format of the `name' is a URI:
2439 `scheme:[//]keyservername[:port]' The scheme is the type of
2440 keyserver: "hkp" for the HTTP (or compatible) keyservers, "ldap"
2441 for the LDAP keyservers, or "mailto" for the Graff email
2442 keyserver. Note that your particular installation of GnuPG may
2443 have other keyserver types available as well. Keyserver schemes
2444 are case-insensitive. After the keyserver name, optional keyserver
2445 configuration options may be provided. These are the same as the
2446 global `--keyserver-options' from below, but apply only to this
2447 particular keyserver.
2449 Most keyservers synchronize with each other, so there is generally
2450 no need to send keys to more than one server. The keyserver
2451 `hkp://keys.gnupg.net' uses round robin DNS to give a different
2452 keyserver each time you use it.
2454 `--keyserver-options `name=value1 ''
2455 This is a space or comma delimited string that gives options for
2456 the keyserver. Options can be prefixed with a `no-' to give the
2457 opposite meaning. Valid import-options or export-options may be
2458 used here as well to apply to importing (`--recv-key') or exporting
2459 (`--send-key') a key from a keyserver. While not all options are
2460 available for all keyserver types, some common options are:
2463 When searching for a key with `--search-keys', include keys
2464 that are marked on the keyserver as revoked. Note that not
2465 all keyservers differentiate between revoked and unrevoked
2466 keys, and for such keyservers this option is meaningless.
2467 Note also that most keyservers do not have cryptographic
2468 verification of key revocations, and so turning this option
2469 off may result in skipping keys that are incorrectly marked
2473 When searching for a key with `--search-keys', include keys
2474 that are marked on the keyserver as disabled. Note that
2475 this option is not used with HKP keyservers.
2478 This option enables the automatic retrieving of keys from a
2479 keyserver when verifying signatures made by keys that are
2480 not on the local keyring.
2482 Note that this option makes a "web bug" like behavior
2483 possible. Keyserver operators can see which keys you
2484 request, so by sending you a message signed by a brand new
2485 key (which you naturally will not have on your local
2486 keyring), the operator can tell both your IP address and
2487 the time when you verified the signature.
2490 When using `--refresh-keys', if the key in question has a
2491 preferred keyserver URL, then use that preferred keyserver
2492 to refresh the key from. In addition, if auto-key-retrieve
2493 is set, and the signature being verified has a preferred
2494 keyserver URL, then use that preferred keyserver to fetch
2495 the key from. Defaults to yes.
2498 If auto-key-retrieve is set, and the signature being verified
2499 has a PKA record, then use the PKA information to fetch the
2500 key. Defaults to yes.
2503 When receiving a key, include subkeys as potential targets.
2504 Note that this option is not used with HKP keyservers, as
2505 they do not support retrieving keys by subkey id.
2508 On most Unix-like platforms, GnuPG communicates with the
2509 keyserver helper program via pipes, which is the most
2510 efficient method. This option forces GnuPG to use temporary
2511 files to communicate. On some platforms (such as Win32 and
2512 RISC OS), this option is always enabled.
2515 If using `use-temp-files', do not delete the temp files after
2516 using them. This option is useful to learn the keyserver
2517 communication protocol by reading the temporary files.
2520 Tell the keyserver helper program to be more verbose. This
2521 option can be repeated multiple times to increase the
2525 Tell the keyserver helper program how long (in seconds) to
2526 try and perform a keyserver action before giving up. Note
2527 that performing multiple actions at the same time uses this
2528 timeout value per action. For example, when retrieving
2529 multiple keys via `--recv-keys', the timeout applies
2530 separately to each key retrieval, and not to the
2531 `--recv-keys' command as a whole. Defaults to 30 seconds.
2534 Set the proxy to use for HTTP and HKP keyservers. This
2535 overrides the "http_proxy" environment variable, if any.
2538 When retrieving a key via DNS CERT, only accept keys up to
2539 this size. Defaults to 16384 bytes.
2542 Turn on debug output in the keyserver helper program. Note
2543 that the details of debug output depends on which keyserver
2544 helper program is being used, and in turn, on any libraries
2545 that the keyserver helper program uses internally (libcurl,
2549 Enable certificate checking if the keyserver presents one
2550 (for hkps or ldaps). Defaults to on.
2553 Provide a certificate store to override the system default.
2554 Only necessary if check-cert is enabled, and the keyserver
2555 is using a certificate that is not present in a system
2556 default certificate list.
2558 Note that depending on the SSL library that the keyserver
2559 helper is built with, this may actually be a directory or a
2562 `--completes-needed `n''
2563 Number of completely trusted users to introduce a new key signer
2566 `--marginals-needed `n''
2567 Number of marginally trusted users to introduce a new key signer
2570 `--max-cert-depth `n''
2571 Maximum depth of a certification chain (default is 5).
2573 `--simple-sk-checksum'
2574 Secret keys are integrity protected by using a SHA-1 checksum. This
2575 method is part of the upcoming enhanced OpenPGP specification but
2576 GnuPG already uses it as a countermeasure against certain attacks.
2577 Old applications don't understand this new format, so this option
2578 may be used to switch back to the old behaviour. Using this option
2579 bears a security risk. Note that using this option only takes
2580 effect when the secret key is encrypted - the simplest way to make
2581 this happen is to change the passphrase on the key (even changing
2582 it to the same value is acceptable).
2585 Do not cache the verification status of key signatures. Caching
2586 gives a much better performance in key listings. However, if you
2587 suspect that your public keyring is not save against write
2588 modifications, you can use this option to disable the caching. It
2589 probably does not make sense to disable it because all kind of
2590 damage can be done if someone else has write access to your public
2593 `--no-sig-create-check'
2594 GnuPG normally verifies each signature right after creation to
2595 protect against bugs and hardware malfunctions which could leak
2596 out bits from the secret key. This extra verification needs some
2597 time (about 115% for DSA keys), and so this option can be used to
2598 disable it. However, due to the fact that the signature creation
2599 needs manual interaction, this performance penalty does not matter
2602 `--auto-check-trustdb'
2603 `--no-auto-check-trustdb'
2604 If GnuPG feels that its information about the Web of Trust has to
2605 be updated, it automatically runs the `--check-trustdb' command
2606 internally. This may be a time consuming process.
2607 `--no-auto-check-trustdb' disables this option.
2611 This is dummy option. `gpg2' always requires the agent.
2614 This is dummy option. It has no effect when used with `gpg2'.
2617 Lock the databases the first time a lock is requested and do not
2618 release the lock until the process terminates.
2621 Release the locks every time a lock is no longer needed. Use this
2622 to override a previous `--lock-once' from a config file.
2625 Disable locking entirely. This option should be used only in very
2626 special environments, where it can be assured that only one process
2627 is accessing those files. A bootable floppy with a stand-alone
2628 encryption system will probably use this. Improper usage of this
2629 option may lead to data and key corruption.
2631 `--exit-on-status-write-error'
2632 This option will cause write errors on the status FD to immediately
2633 terminate the process. That should in fact be the default but it
2634 never worked this way and thus we need an option to enable this,
2635 so that the change won't break applications which close their end
2636 of a status fd connected pipe too early. Using this option along
2637 with `--enable-progress-filter' may be used to cleanly cancel long
2638 running gpg operations.
2640 `--limit-card-insert-tries `n''
2641 With `n' greater than 0 the number of prompts asking to insert a
2642 smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
2643 all ask to insert a card if none has been inserted at startup. This
2644 option is useful in the configuration file in case an application
2645 does not know about the smartcard support and waits ad infinitum
2646 for an inserted card.
2648 `--no-random-seed-file'
2649 GnuPG uses a file to store its internal random pool over
2650 invocations. This makes random generation faster; however
2651 sometimes write operations are not desired. This option can be
2652 used to achieve that with the cost of slower random generation.
2655 Suppress the initial copyright message.
2657 `--no-secmem-warning'
2658 Suppress the warning about "using insecure memory".
2660 `--no-permission-warning'
2661 Suppress the warning about unsafe file and home directory
2662 (`--homedir') permissions. Note that the permission checks that
2663 GnuPG performs are not intended to be authoritative, but rather
2664 they simply warn about certain common permission problems. Do not
2665 assume that the lack of a warning means that your system is secure.
2667 Note that the warning for unsafe `--homedir' permissions cannot be
2668 suppressed in the gpg.conf file, as this would allow an attacker to
2669 place an unsafe gpg.conf file in place, and use this file to
2670 suppress warnings about itself. The `--homedir' permissions
2671 warning may only be suppressed on the command line.
2674 Suppress the warning about missing MDC integrity protection.
2677 `--no-require-secmem'
2678 Refuse to run if GnuPG cannot get secure memory. Defaults to no
2679 (i.e. run, but give a warning).
2681 `--require-cross-certification'
2682 `--no-require-cross-certification'
2683 When verifying a signature made from a subkey, ensure that the
2684 cross certification "back signature" on the subkey is present and
2685 valid. This protects against a subtle attack against subkeys that
2686 can sign. Defaults to `--require-cross-certification' for `gpg2'.
2690 Allow the user to do certain nonsensical or "silly" things like
2691 signing an expired or revoked key, or certain potentially
2692 incompatible things like generating unusual key types. This also
2693 disables certain warning messages about potentially incompatible
2694 actions. As the name implies, this option is for experts only. If
2695 you don't fully understand the implications of what it allows you
2696 to do, leave this off. `--no-expert' disables this option.
2700 File: gnupg.info, Node: GPG Key related Options, Next: GPG Input and Output, Prev: GPG Configuration Options, Up: GPG Options
2702 3.2.2 Key related options
2703 -------------------------
2707 Encrypt for user id NAME. If this option or `--hidden-recipient'
2708 is not specified, GnuPG asks for the user-id unless
2709 `--default-recipient' is given.
2711 `--hidden-recipient NAME'
2713 Encrypt for user ID NAME, but hide the key ID of this user's key.
2714 This option helps to hide the receiver of the message and is a
2715 limited countermeasure against traffic analysis. If this option or
2716 `--recipient' is not specified, GnuPG asks for the user ID unless
2717 `--default-recipient' is given.
2719 `--encrypt-to `name''
2720 Same as `--recipient' but this one is intended for use in the
2721 options file and may be used with your own user-id as an
2722 "encrypt-to-self". These keys are only used when there are other
2723 recipients given either by use of `--recipient' or by the asked
2724 user id. No trust checking is performed for these user ids and
2725 even disabled keys can be used.
2727 `--hidden-encrypt-to `name''
2728 Same as `--hidden-recipient' but this one is intended for use in
2729 the options file and may be used with your own user-id as a hidden
2730 "encrypt-to-self". These keys are only used when there are other
2731 recipients given either by use of `--recipient' or by the asked
2732 user id. No trust checking is performed for these user ids and
2733 even disabled keys can be used.
2736 Disable the use of all `--encrypt-to' and `--hidden-encrypt-to'
2739 `--group `name=value1 ''
2740 Sets up a named group, which is similar to aliases in email
2741 programs. Any time the group name is a recipient (`-r' or
2742 `--recipient'), it will be expanded to the values specified.
2743 Multiple groups with the same name are automatically merged into a
2746 The values are `key IDs' or fingerprints, but any key description
2747 is accepted. Note that a value with spaces in it will be treated as
2748 two different values. Note also there is only one level of
2749 expansion -- you cannot make an group that points to another
2750 group. When used from the command line, it may be necessary to
2751 quote the argument to this option to prevent the shell from
2752 treating it as multiple arguments.
2755 Remove a given entry from the `--group' list.
2758 Remove all entries from the `--group' list.
2762 Use NAME as the key to sign with. Note that this option overrides
2766 Don't look at the key ID as stored in the message but try all
2767 secret keys in turn to find the right decryption key. This option
2768 forces the behaviour as used by anonymous recipients (created by
2769 using `--throw-keyids' or `--hidden-recipient') and might come
2770 handy in case where an encrypted message contains a bogus key ID.
2772 `--skip-hidden-recipients'
2773 `--no-skip-hidden-recipients'
2774 During decryption skip all anonymous recipients. This option
2775 helps in the case that people use the hidden recipients feature to
2776 hide there own encrypt-to key from others. If oneself has many
2777 secret keys this may lead to a major annoyance because all keys
2778 are tried in turn to decrypt soemthing which was not really
2779 intended for it. The drawback of this option is that it is
2780 currently not possible to decrypt a message which includes real
2781 anonymous recipients.
2785 File: gnupg.info, Node: GPG Input and Output, Next: OpenPGP Options, Prev: GPG Key related Options, Up: GPG Options
2787 3.2.3 Input and Output
2788 ----------------------
2792 Create ASCII armored output. The default is to create the binary
2796 Assume the input data is not in ASCII armored format.
2800 Write output to FILE.
2803 This option sets a limit on the number of bytes that will be
2804 generated when processing a file. Since OpenPGP supports various
2805 levels of compression, it is possible that the plaintext of a
2806 given message may be significantly larger than the original
2807 OpenPGP message. While GnuPG works properly with such messages,
2808 there is often a desire to set a maximum file size that will be
2809 generated before processing is forced to stop by the OS limits.
2810 Defaults to 0, which means "no limit".
2812 `--import-options `parameters''
2813 This is a space or comma delimited string that gives options for
2814 importing keys. Options can be prepended with a `no-' to give the
2815 opposite meaning. The options are:
2818 Allow importing key signatures marked as "local". This is not
2819 generally useful unless a shared keyring scheme is being
2820 used. Defaults to no.
2822 repair-pks-subkey-bug
2823 During import, attempt to repair the damage caused by the PKS
2824 keyserver bug (pre version 0.9.6) that mangles keys with
2825 multiple subkeys. Note that this cannot completely repair
2826 the damaged key as some crucial data is removed by the
2827 keyserver, but it does at least give you back one subkey.
2828 Defaults to no for regular `--import' and to yes for
2829 keyserver `--recv-keys'.
2832 During import, allow key updates to existing keys, but do not
2833 allow any new keys to be imported. Defaults to no.
2836 After import, compact (remove all signatures except the
2837 self-signature) any user IDs from the new key that are not
2838 usable. Then, remove any signatures from the new key that
2839 are not usable. This includes signatures that were issued
2840 by keys that are not present on the keyring. This option is
2841 the same as running the `--edit-key' command "clean" after
2842 import. Defaults to no.
2845 Import the smallest key possible. This removes all signatures
2846 except the most recent self-signature on each user ID. This
2847 option is the same as running the `--edit-key' command
2848 "minimize" after import. Defaults to no.
2850 `--export-options `parameters''
2851 This is a space or comma delimited string that gives options for
2852 exporting keys. Options can be prepended with a `no-' to give the
2853 opposite meaning. The options are:
2856 Allow exporting key signatures marked as "local". This is not
2857 generally useful unless a shared keyring scheme is being
2858 used. Defaults to no.
2861 Include attribute user IDs (photo IDs) while exporting. This
2862 is useful to export keys if they are going to be used by an
2863 OpenPGP program that does not accept attribute user IDs.
2866 export-sensitive-revkeys
2867 Include designated revoker information that was marked as
2868 "sensitive". Defaults to no.
2870 export-reset-subkey-passwd
2871 When using the `--export-secret-subkeys' command, this option
2872 resets the passphrases for all exported subkeys to empty.
2873 This is useful when the exported subkey is to be used on an
2874 unattended machine where a passphrase doesn't necessarily
2875 make sense. Defaults to no.
2878 Compact (remove all signatures from) user IDs on the key being
2879 exported if the user IDs are not usable. Also, do not export
2880 any signatures that are not usable. This includes
2881 signatures that were issued by keys that are not present on
2882 the keyring. This option is the same as running the
2883 `--edit-key' command "clean" before export except that the
2884 local copy of the key is not modified. Defaults to no.
2887 Export the smallest key possible. This removes all signatures
2888 except the most recent self-signature on each user ID. This
2889 option is the same as running the `--edit-key' command
2890 "minimize" before export except that the local copy of the
2891 key is not modified. Defaults to no.
2894 Print key listings delimited by colons. Note that the output will
2895 be encoded in UTF-8 regardless of any `--display-charset' setting.
2896 This format is useful when GnuPG is called from scripts and other
2897 programs as it is easily machine parsed. The details of this
2898 format are documented in the file `doc/DETAILS', which is included
2899 in the GnuPG source distribution.
2902 Do not merge primary user ID and primary key in `--with-colon'
2903 listing mode and print all timestamps as seconds since 1970-01-01.
2904 Since GnuPG 2.0.10, this mode is always used and thus this option
2905 is obsolete; it does not harm to use it though.
2907 `--with-fingerprint'
2908 Same as the command `--fingerprint' but changes only the format of
2909 the output and may be used together with another command.
2913 File: gnupg.info, Node: OpenPGP Options, Next: GPG Esoteric Options, Prev: GPG Input and Output, Up: GPG Options
2915 3.2.4 OpenPGP protocol specific options.
2916 ----------------------------------------
2920 Treat input files as text and store them in the OpenPGP canonical
2921 text form with standard "CRLF" line endings. This also sets the
2922 necessary flags to inform the recipient that the encrypted or
2923 signed data is text and may need its line endings converted back
2924 to whatever the local system uses. This option is useful when
2925 communicating between two platforms that have different line
2926 ending conventions (UNIX-like to Mac, Mac to Windows, etc).
2927 `--no-textmode' disables this option, and is the default.
2930 `--no-force-v3-sigs'
2931 OpenPGP states that an implementation should generate v4 signatures
2932 but PGP versions 5 through 7 only recognize v4 signatures on key
2933 material. This option forces v3 signatures for signatures on data.
2934 Note that this option implies `--no-ask-sig-expire', and unsets
2935 `--sig-policy-url', `--sig-notation', and `--sig-keyserver-url',
2936 as these features cannot be used with v3 signatures.
2937 `--no-force-v3-sigs' disables this option. Defaults to no.
2940 `--no-force-v4-certs'
2941 Always use v4 key signatures even on v3 keys. This option also
2942 changes the default hash algorithm for v3 RSA keys from MD5 to
2943 SHA-1. `--no-force-v4-certs' disables this option.
2946 Force the use of encryption with a modification detection code.
2947 This is always used with the newer ciphers (those with a blocksize
2948 greater than 64 bits), or if all of the recipient keys indicate
2949 MDC support in their feature flags.
2952 Disable the use of the modification detection code. Note that by
2953 using this option, the encrypted message becomes vulnerable to a
2954 message modification attack.
2956 `--personal-cipher-preferences `string''
2957 Set the list of personal cipher preferences to `string'. Use
2958 `gpg2 --version' to get a list of available algorithms, and use
2959 `none' to set no preference at all. This allows the user to
2960 safely override the algorithm chosen by the recipient key
2961 preferences, as GPG will only select an algorithm that is usable by
2962 all recipients. The most highly ranked cipher in this list is also
2963 used for the `--symmetric' encryption command.
2965 `--personal-digest-preferences `string''
2966 Set the list of personal digest preferences to `string'. Use
2967 `gpg2 --version' to get a list of available algorithms, and use
2968 `none' to set no preference at all. This allows the user to
2969 safely override the algorithm chosen by the recipient key
2970 preferences, as GPG will only select an algorithm that is usable by
2971 all recipients. The most highly ranked digest algorithm in this
2972 list is also used when signing without encryption (e.g.
2973 `--clearsign' or `--sign').
2975 `--personal-compress-preferences `string''
2976 Set the list of personal compression preferences to `string'. Use
2977 `gpg2 --version' to get a list of available algorithms, and use
2978 `none' to set no preference at all. This allows the user to
2979 safely override the algorithm chosen by the recipient key
2980 preferences, as GPG will only select an algorithm that is usable
2981 by all recipients. The most highly ranked compression algorithm
2982 in this list is also used when there are no recipient keys to
2983 consider (e.g. `--symmetric').
2985 `--s2k-cipher-algo `name''
2986 Use `name' as the cipher algorithm used to protect secret keys.
2987 The default cipher is CAST5. This cipher is also used for
2988 conventional encryption if `--personal-cipher-preferences' and
2989 `--cipher-algo' is not given.
2991 `--s2k-digest-algo `name''
2992 Use `name' as the digest algorithm used to mangle the passphrases.
2993 The default algorithm is SHA-1.
2996 Selects how passphrases are mangled. If `n' is 0 a plain
2997 passphrase (which is not recommended) will be used, a 1 adds a
2998 salt to the passphrase and a 3 (the default) iterates the whole
2999 process a number of times (see -s2k-count). Unless `--rfc1991' is
3000 used, this mode is also used for conventional encryption.
3003 Specify how many times the passphrase mangling is repeated. This
3004 value may range between 1024 and 65011712 inclusive. The default
3005 is inquired from gpg-agent. Note that not all values in the
3006 1024-65011712 range are legal and if an illegal value is selected,
3007 GnuPG will round up to the nearest legal value. This option is
3008 only meaningful if `--s2k-mode' is 3.
3011 3.2.5 Compliance options
3012 ------------------------
3014 These options control what GnuPG is compliant to. Only one of these
3015 options may be active at a time. Note that the default setting of this
3016 is nearly always the correct one. See the INTEROPERABILITY WITH OTHER
3017 OPENPGP PROGRAMS section below before using one of these options.
3020 Use standard GnuPG behavior. This is essentially OpenPGP behavior
3021 (see `--openpgp'), but with some additional workarounds for common
3022 compatibility problems in different versions of PGP. This is the
3023 default option, so it is not generally needed, but it may be
3024 useful to override a different compliance option in the gpg.conf
3028 Reset all packet, cipher and digest options to strict OpenPGP
3029 behavior. Use this option to reset all previous options like
3030 `--s2k-*', `--cipher-algo', `--digest-algo' and `--compress-algo'
3031 to OpenPGP compliant values. All PGP workarounds are disabled.
3034 Reset all packet, cipher and digest options to strict RFC-4880
3035 behavior. Note that this is currently the same thing as
3039 Reset all packet, cipher and digest options to strict RFC-2440
3043 Try to be more RFC-1991 (PGP 2.x) compliant.
3046 Set up all options to be as PGP 2.x compliant as possible, and
3047 warn if an action is taken (e.g. encrypting to a non-RSA key) that
3048 will create a message that PGP 2.x will not be able to handle.
3049 Note that `PGP 2.x' here means `MIT PGP 2.6.2'. There are other
3050 versions of PGP 2.x available, but the MIT release is a good
3053 This option implies `--rfc1991 --disable-mdc --no-force-v4-certs
3054 --escape-from-lines --force-v3-sigs --cipher-algo IDEA
3055 --digest-algo MD5 --compress-algo ZIP'. It also disables
3056 `--textmode' when encrypting.
3059 Set up all options to be as PGP 6 compliant as possible. This
3060 restricts you to the ciphers IDEA (if the IDEA plugin is
3061 installed), 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160,
3062 and the compression algorithms none and ZIP. This also disables
3063 -throw-keyids, and making signatures with signing subkeys as PGP 6
3064 does not understand signatures made by signing subkeys.
3066 This option implies `--disable-mdc --escape-from-lines
3070 Set up all options to be as PGP 7 compliant as possible. This is
3071 identical to `--pgp6' except that MDCs are not disabled, and the
3072 list of allowable ciphers is expanded to add AES128, AES192,
3073 AES256, and TWOFISH.
3076 Set up all options to be as PGP 8 compliant as possible. PGP 8 is
3077 a lot closer to the OpenPGP standard than previous versions of
3078 PGP, so all this does is disable `--throw-keyids' and set
3079 `--escape-from-lines'. All algorithms are allowed except for the
3080 SHA224, SHA384, and SHA512 digests.
3084 File: gnupg.info, Node: GPG Esoteric Options, Prev: OpenPGP Options, Up: GPG Options
3086 3.2.6 Doing things one usually doesn't want to do.
3087 --------------------------------------------------
3091 Don't make any changes (this is not completely implemented).
3094 Changes the behaviour of some commands. This is like `--dry-run'
3095 but different in some cases. The semantic of this command may be
3096 extended in the future. Currently it only skips the actual
3097 decryption pass and therefore enables a fast listing of the
3102 Prompt before overwriting any files.
3104 `--debug-level LEVEL'
3105 Select the debug level for investigating problems. LEVEL may be a
3106 numeric value or by a keyword:
3109 No debugging at all. A value of less than 1 may be used
3110 instead of the keyword.
3113 Some basic debug messages. A value between 1 and 2 may be
3114 used instead of the keyword.
3117 More verbose debug messages. A value between 3 and 5 may be
3118 used instead of the keyword.
3121 Even more detailed messages. A value between 6 and 8 may be
3122 used instead of the keyword.
3125 All of the debug messages you can get. A value greater than 8
3126 may be used instead of the keyword. The creation of hash
3127 tracing files is only enabled if the keyword is used.
3129 How these messages are mapped to the actual debugging flags is not
3130 specified and may change with newer releases of this program. They
3131 are however carefully selected to best aid in debugging.
3134 Set debugging flags. All flags are or-ed and FLAGS may be given in
3135 C syntax (e.g. 0x0042).
3138 Set all useful debugging flags.
3140 `--faked-system-time EPOCH'
3141 This option is only useful for testing; it sets the system time
3142 back or forth to EPOCH which is the number of seconds elapsed
3143 since the year 1970. Alternatively EPOCH may be given as a full
3144 ISO time string (e.g. "20070924T154812").
3146 `--enable-progress-filter'
3147 Enable certain PROGRESS status outputs. This option allows
3148 frontends to display a progress indicator while gpg is processing
3149 larger files. There is a slight performance overhead using it.
3152 Write special status strings to the file descriptor `n'. See the
3153 file DETAILS in the documentation for a listing of them.
3155 `--status-file `file''
3156 Same as `--status-fd', except the status data is written to file
3160 Write log output to file descriptor `n' and not to STDERR.
3163 `--logger-file `file''
3164 Same as `--logger-fd', except the logger data is written to file
3165 `file'. Note that `--log-file' is only implemented for GnuPG-2.
3167 `--attribute-fd `n''
3168 Write attribute subpackets to the file descriptor `n'. This is most
3169 useful for use with `--status-fd', since the status messages are
3170 needed to separate out the various subpackets from the stream
3171 delivered to the file descriptor.
3173 `--attribute-file `file''
3174 Same as `--attribute-fd', except the attribute data is written to
3177 `--comment `string''
3179 Use `string' as a comment string in clear text signatures and ASCII
3180 armored messages or keys (see `--armor'). The default behavior is
3181 not to use a comment string. `--comment' may be repeated multiple
3182 times to get multiple comment strings. `--no-comments' removes all
3183 comments. It is a good idea to keep the length of a single comment
3184 below 60 characters to avoid problems with mail programs wrapping
3185 such lines. Note that comment lines, like all other header lines,
3186 are not protected by the signature.
3190 Force inclusion of the version string in ASCII armored output.
3191 `--no-emit-version' disables this option.
3193 `--sig-notation `name=value''
3194 `--cert-notation `name=value''
3195 `-N, --set-notation `name=value''
3196 Put the name value pair into the signature as notation data.
3197 `name' must consist only of printable characters or spaces, and
3198 must contain a '@' character in the form keyname@domain.example.com
3199 (substituting the appropriate keyname and domain name, of course).
3200 This is to help prevent pollution of the IETF reserved notation
3201 namespace. The `--expert' flag overrides the '@' check. `value'
3202 may be any printable string; it will be encoded in UTF8, so you
3203 should check that your `--display-charset' is set correctly. If
3204 you prefix `name' with an exclamation mark (!), the notation data
3205 will be flagged as critical (rfc2440:5.2.3.15). `--sig-notation'
3206 sets a notation for data signatures. `--cert-notation' sets a
3207 notation for key signatures (certifications). `--set-notation'
3210 There are special codes that may be used in notation names. "%k"
3211 will be expanded into the key ID of the key being signed, "%K"
3212 into the long key ID of the key being signed, "%f" into the
3213 fingerprint of the key being signed, "%s" into the key ID of the
3214 key making the signature, "%S" into the long key ID of the key
3215 making the signature, "%g" into the fingerprint of the key making
3216 the signature (which might be a subkey), "%p" into the fingerprint
3217 of the primary key of the key making the signature, "%c" into the
3218 signature count from the OpenPGP smartcard, and "%%" results in a
3219 single "%". %k, %K, and %f are only meaningful when making a key
3220 signature (certification), and %c is only meaningful when using
3221 the OpenPGP smartcard.
3223 `--sig-policy-url `string''
3224 `--cert-policy-url `string''
3225 `--set-policy-url `string''
3226 Use `string' as a Policy URL for signatures (rfc2440:5.2.3.19). If
3227 you prefix it with an exclamation mark (!), the policy URL packet
3228 will be flagged as critical. `--sig-policy-url' sets a policy url
3229 for data signatures. `--cert-policy-url' sets a policy url for key
3230 signatures (certifications). `--set-policy-url' sets both.
3232 The same %-expandos used for notation data are available here as
3235 `--sig-keyserver-url `string''
3236 Use `string' as a preferred keyserver URL for data signatures. If
3237 you prefix it with an exclamation mark (!), the keyserver URL
3238 packet will be flagged as critical.
3240 The same %-expandos used for notation data are available here as
3243 `--set-filename `string''
3244 Use `string' as the filename which is stored inside messages.
3245 This overrides the default, which is to use the actual filename of
3246 the file being encrypted.
3248 `--for-your-eyes-only'
3249 `--no-for-your-eyes-only'
3250 Set the `for your eyes only' flag in the message. This causes
3251 GnuPG to refuse to save the file unless the `--output' option is
3252 given, and PGP to use a "secure viewer" with a claimed
3253 Tempest-resistant font to display the message. This option
3254 overrides `--set-filename'. `--no-for-your-eyes-only' disables
3257 `--use-embedded-filename'
3258 `--no-use-embedded-filename'
3259 Try to create a file with a name as embedded in the data. This can
3260 be a dangerous option as it allows to overwrite files. Defaults to
3263 `--cipher-algo `name''
3264 Use `name' as cipher algorithm. Running the program with the
3265 command `--version' yields a list of supported algorithms. If this
3266 is not used the cipher algorithm is selected from the preferences
3267 stored with the key. In general, you do not want to use this
3268 option as it allows you to violate the OpenPGP standard.
3269 `--personal-cipher-preferences' is the safe way to accomplish the
3272 `--digest-algo `name''
3273 Use `name' as the message digest algorithm. Running the program
3274 with the command `--version' yields a list of supported
3275 algorithms. In general, you do not want to use this option as it
3276 allows you to violate the OpenPGP standard.
3277 `--personal-digest-preferences' is the safe way to accomplish the
3280 `--compress-algo `name''
3281 Use compression algorithm `name'. "zlib" is RFC-1950 ZLIB
3282 compression. "zip" is RFC-1951 ZIP compression which is used by
3283 PGP. "bzip2" is a more modern compression scheme that can
3284 compress some things better than zip or zlib, but at the cost of
3285 more memory used during compression and decompression.
3286 "uncompressed" or "none" disables compression. If this option is
3287 not used, the default behavior is to examine the recipient key
3288 preferences to see which algorithms the recipient supports. If all
3289 else fails, ZIP is used for maximum compatibility.
3291 ZLIB may give better compression results than ZIP, as the
3292 compression window size is not limited to 8k. BZIP2 may give even
3293 better compression results than that, but will use a significantly
3294 larger amount of memory while compressing and decompressing. This
3295 may be significant in low memory situations. Note, however, that
3296 PGP (all versions) only supports ZIP compression. Using any
3297 algorithm other than ZIP or "none" will make the message
3298 unreadable with PGP. In general, you do not want to use this
3299 option as it allows you to violate the OpenPGP standard.
3300 `--personal-compress-preferences' is the safe way to accomplish
3303 `--cert-digest-algo `name''
3304 Use `name' as the message digest algorithm used when signing a
3305 key. Running the program with the command `--version' yields a
3306 list of supported algorithms. Be aware that if you choose an
3307 algorithm that GnuPG supports but other OpenPGP implementations do
3308 not, then some users will not be able to use the key signatures
3309 you make, or quite possibly your entire key.
3311 `--disable-cipher-algo `name''
3312 Never allow the use of `name' as cipher algorithm. The given name
3313 will not be checked so that a later loaded algorithm will still
3316 `--disable-pubkey-algo `name''
3317 Never allow the use of `name' as public key algorithm. The given
3318 name will not be checked so that a later loaded algorithm will
3323 Do not put the recipient key IDs into encrypted messages. This
3324 helps to hide the receivers of the message and is a limited
3325 countermeasure against traffic analysis.(1) On the receiving
3326 side, it may slow down the decryption process because all
3327 available secret keys must be tried. `--no-throw-keyids' disables
3328 this option. This option is essentially the same as using
3329 `--hidden-recipient' for all recipients.
3331 `--not-dash-escaped'
3332 This option changes the behavior of cleartext signatures so that
3333 they can be used for patch files. You should not send such an
3334 armored file via email because all spaces and line endings are
3335 hashed too. You can not use this option for data which has 5
3336 dashes at the beginning of a line, patch files don't have this. A
3337 special armor header line tells GnuPG about this cleartext
3340 `--escape-from-lines'
3341 `--no-escape-from-lines'
3342 Because some mailers change lines starting with "From " to ">From
3343 " it is good to handle such lines in a special way when creating
3344 cleartext signatures to prevent the mail system from breaking the
3345 signature. Note that all other PGP versions do it this way too.
3346 Enabled by default. `--no-escape-from-lines' disables this option.
3348 `--passphrase-repeat `n''
3349 Specify how many times `gpg2' will request a new passphrase be
3350 repeated. This is useful for helping memorize a passphrase.
3351 Defaults to 1 repetition.
3353 `--passphrase-fd `n''
3354 Read the passphrase from file descriptor `n'. Only the first line
3355 will be read from file descriptor `n'. If you use 0 for `n', the
3356 passphrase will be read from STDIN. This can only be used if only
3357 one passphrase is supplied. Note that this passphrase is only
3358 used if the option `--batch' has also been given. This is
3359 different from `gpg'.
3361 `--passphrase-file `file''
3362 Read the passphrase from file `file'. Only the first line will be
3363 read from file `file'. This can only be used if only one
3364 passphrase is supplied. Obviously, a passphrase stored in a file is
3365 of questionable security if other users can read this file. Don't
3366 use this option if you can avoid it. Note that this passphrase is
3367 only used if the option `--batch' has also been given. This is
3368 different from `gpg'.
3370 `--passphrase `string''
3371 Use `string' as the passphrase. This can only be used if only one
3372 passphrase is supplied. Obviously, this is of very questionable
3373 security on a multi-user system. Don't use this option if you can
3374 avoid it. Note that this passphrase is only used if the option
3375 `--batch' has also been given. This is different from `gpg'.
3378 This is a replacement for the deprecated shared-memory IPC mode.
3379 If this option is enabled, user input on questions is not expected
3380 from the TTY but from the given file descriptor. It should be used
3381 together with `--status-fd'. See the file doc/DETAILS in the source
3382 distribution for details on how to use it.
3384 `--command-file `file''
3385 Same as `--command-fd', except the commands are read out of file
3388 `--allow-non-selfsigned-uid'
3389 `--no-allow-non-selfsigned-uid'
3390 Allow the import and use of keys with user IDs which are not
3391 self-signed. This is not recommended, as a non self-signed user ID
3392 is trivial to forge. `--no-allow-non-selfsigned-uid' disables.
3394 `--allow-freeform-uid'
3395 Disable all checks on the form of the user ID while generating a
3396 new one. This option should only be used in very special
3397 environments as it does not ensure the de-facto standard format of
3400 `--ignore-time-conflict'
3401 GnuPG normally checks that the timestamps associated with keys and
3402 signatures have plausible values. However, sometimes a signature
3403 seems to be older than the key due to clock problems. This option
3404 makes these checks just a warning. See also `--ignore-valid-from'
3405 for timestamp issues on subkeys.
3407 `--ignore-valid-from'
3408 GnuPG normally does not select and use subkeys created in the
3409 future. This option allows the use of such keys and thus exhibits
3410 the pre-1.0.7 behaviour. You should not use this option unless
3411 there is some clock problem. See also `--ignore-time-conflict' for
3412 timestamp issues with signatures.
3414 `--ignore-crc-error'
3415 The ASCII armor used by OpenPGP is protected by a CRC checksum
3416 against transmission errors. Occasionally the CRC gets mangled
3417 somewhere on the transmission channel but the actual content
3418 (which is protected by the OpenPGP protocol anyway) is still okay.
3419 This option allows GnuPG to ignore CRC errors.
3421 `--ignore-mdc-error'
3422 This option changes a MDC integrity protection failure into a
3423 warning. This can be useful if a message is partially corrupt,
3424 but it is necessary to get as much data as possible out of the
3425 corrupt message. However, be aware that a MDC protection failure
3426 may also mean that the message was tampered with intentionally by
3429 `--no-default-keyring'
3430 Do not add the default keyrings to the list of keyrings. Note that
3431 GnuPG will not operate without any keyrings, so if you use this
3432 option and do not provide alternate keyrings via `--keyring' or
3433 `--secret-keyring', then GnuPG will still use the default public or
3437 Skip the signature verification step. This may be used to make the
3438 decryption faster if the signature verification is not needed.
3441 Print key listings delimited by colons (like `--with-colons') and
3442 print the public key data.
3445 Changes the output of the list commands to work faster; this is
3446 achieved by leaving some parts empty. Some applications don't need
3447 the user ID and the trust information given in the listings. By
3448 using this options they can get a faster listing. The exact
3449 behaviour of this option may change in future versions. If you
3450 are missing some information, don't use this option.
3453 This is not for normal use. Use the source to see for what it
3457 This is not for normal use. Use the source to see for what it
3460 `--show-session-key'
3461 Display the session key used for one message. See
3462 `--override-session-key' for the counterpart of this option.
3464 We think that Key Escrow is a Bad Thing; however the user should
3465 have the freedom to decide whether to go to prison or to reveal
3466 the content of one specific message without compromising all
3467 messages ever encrypted for one secret key. DON'T USE IT UNLESS
3468 YOU ARE REALLY FORCED TO DO SO.
3470 `--override-session-key `string''
3471 Don't use the public key but the session key `string'. The format
3472 of this string is the same as the one printed by
3473 `--show-session-key'. This option is normally not used but comes
3474 handy in case someone forces you to reveal the content of an
3475 encrypted message; using this option you can do this without
3476 handing out the secret key.
3479 `--no-ask-sig-expire'
3480 When making a data signature, prompt for an expiration time. If
3481 this option is not specified, the expiration time set via
3482 `--default-sig-expire' is used. `--no-ask-sig-expire' disables
3485 `--default-sig-expire'
3486 The default expiration time to use for signature expiration. Valid
3487 values are "0" for no expiration, a number followed by the letter d
3488 (for days), w (for weeks), m (for months), or y (for years) (for
3489 example "2m" for two months, or "5y" for five years), or an
3490 absolute date in the form YYYY-MM-DD. Defaults to "0".
3493 `--no-ask-cert-expire'
3494 When making a key signature, prompt for an expiration time. If this
3495 option is not specified, the expiration time set via
3496 `--default-cert-expire' is used. `--no-ask-cert-expire' disables
3499 `--default-cert-expire'
3500 The default expiration time to use for key signature expiration.
3501 Valid values are "0" for no expiration, a number followed by the
3502 letter d (for days), w (for weeks), m (for months), or y (for
3503 years) (for example "2m" for two months, or "5y" for five years),
3504 or an absolute date in the form YYYY-MM-DD. Defaults to "0".
3506 `--allow-secret-key-import'
3507 This is an obsolete option and is not used anywhere.
3509 `--allow-multiple-messages'
3511 `--no-allow-multiple-messages'
3512 Allow processing of multiple OpenPGP messages contained in a
3513 single file or stream. Some programs that call GPG are not
3514 prepared to deal with multiple messages being processed together,
3515 so this option defaults to no. Note that versions of GPG prior to
3516 1.4.7 always allowed multiple messages.
3518 Warning: Do not use this option unless you need it as a temporary
3521 `--enable-special-filenames'
3522 This options enables a mode in which filenames of the form `-&n',
3523 where n is a non-negative decimal number, refer to the file
3524 descriptor n and not to a file with that name.
3526 `--no-expensive-trust-checks'
3527 Experimental use only.
3529 `--preserve-permissions'
3530 Don't change the permissions of a secret keyring back to user
3531 read/write only. Use this option only if you really know what you
3534 `--default-preference-list `string''
3535 Set the list of default preferences to `string'. This preference
3536 list is used for new keys and becomes the default for "setpref" in
3539 `--default-keyserver-url `name''
3540 Set the default keyserver URL to `name'. This keyserver will be
3541 used as the keyserver URL when writing a new self-signature on a
3542 key, which includes key generation and changing preferences.
3545 Display various internal configuration parameters of GnuPG. This
3546 option is intended for external programs that call GnuPG to
3547 perform tasks, and is thus not generally useful. See the file
3548 `doc/DETAILS' in the source distribution for the details of which
3549 configuration items may be listed. `--list-config' is only usable
3550 with `--with-colons' set.
3553 This command is similar to `--list-config' but in general only
3554 internally used by the `gpgconf' tool.
3557 This is more or less dummy action. However it parses the
3558 configuration file and returns with failure if the configuration
3559 file would prevent `gpg' from startup. Thus it may be used to run
3560 a syntax check on the configuration file.
3563 3.2.7 Deprecated options
3564 ------------------------
3568 Causes `--list-keys', `--list-sigs', `--list-public-keys',
3569 `--list-secret-keys', and verifying a signature to also display
3570 the photo ID attached to the key, if any. See also
3571 `--photo-viewer'. These options are deprecated. Use
3572 `--list-options [no-]show-photos' and/or `--verify-options
3573 [no-]show-photos' instead.
3576 Display the keyring name at the head of key listings to show which
3577 keyring a given key resides on. This option is deprecated: use
3578 `--list-options [no-]show-keyring' instead.
3581 Identical to `--trust-model always'. This option is deprecated.
3584 `--no-show-notation'
3585 Show signature notations in the `--list-sigs' or `--check-sigs'
3586 listings as well as when verifying a signature with a notation in
3587 it. These options are deprecated. Use `--list-options
3588 [no-]show-notation' and/or `--verify-options [no-]show-notation'
3592 `--no-show-policy-url'
3593 Show policy URLs in the `--list-sigs' or `--check-sigs' listings
3594 as well as when verifying a signature with a policy URL in it.
3595 These options are deprecated. Use `--list-options
3596 [no-]show-policy-url' and/or `--verify-options
3597 [no-]show-policy-url' instead.
3600 ---------- Footnotes ----------
3602 (1) Using a little social engineering anyone who is able to decrypt
3603 the message can check whether one of the other recipients is the one he
3607 File: gnupg.info, Node: GPG Configuration, Next: GPG Examples, Prev: GPG Options, Up: Invoking GPG
3609 3.3 Configuration files
3610 =======================
3612 There are a few configuration files to control certain aspects of
3613 `gpg2''s operation. Unless noted, they are expected in the current home
3614 directory (*note option --homedir::).
3617 This is the standard configuration file read by `gpg2' on
3618 startup. It may contain any valid long option; the leading two
3619 dashes may not be entered and the option may not be abbreviated.
3620 This default name may be changed on the command line (*note
3621 option --options::). You should backup this file.
3624 Note that on larger installations, it is useful to put predefined
3625 files into the directory `/etc/skel/.gnupg/' so that newly created users
3626 start up with a working configuration. For existing users the a small
3627 helper script is provided to create these files (*note addgnupghome::).
3629 For internal purposes `gpg2' creates and maintains a few other
3630 files; They all live in in the current home directory (*note option
3631 --homedir::). Only the `gpg2' may modify these files.
3633 `~/.gnupg/secring.gpg'
3634 The secret keyring. You should backup this file.
3636 `~/.gnupg/secring.gpg.lock'
3637 The lock file for the secret keyring.
3639 `~/.gnupg/pubring.gpg'
3640 The public keyring. You should backup this file.
3642 `~/.gnupg/pubring.gpg.lock'
3643 The lock file for the public keyring.
3645 `~/.gnupg/trustdb.gpg'
3646 The trust database. There is no need to backup this file; it is
3647 better to backup the ownertrust values (*note option
3648 --export-ownertrust::).
3650 `~/.gnupg/trustdb.gpg.lock'
3651 The lock file for the trust database.
3653 `~/.gnupg/random_seed'
3654 A file used to preserve the state of the internal random pool.
3656 `/usr[/local]/share/gnupg/options.skel'
3657 The skeleton options file.
3659 `/usr[/local]/lib/gnupg/'
3660 Default location for extensions.
3663 Operation is further controlled by a few environment variables:
3666 Used to locate the default home directory.
3669 If set directory used instead of "~/.gnupg".
3672 Used to locate the gpg-agent. The value consists of 3 colon
3673 delimited fields: The first is the path to the Unix Domain
3674 Socket, the second the PID of the gpg-agent and the protocol
3675 version which should be set to 1. When starting the gpg-agent as
3676 described in its documentation, this variable is set to the correct
3677 value. The option `--gpg-agent-info' can be used to override it.
3680 This value is passed via gpg-agent to pinentry. It is useful to
3681 convey extra information to a custom pinentry.
3685 Used to size some displays to the full size of the screen.
3688 Apart from its use by GNU, it is used in the W32 version to
3689 override the language selection done through the Registry. If
3690 used and set to a valid and available language name (LANGID),
3691 the file with the translation is loaded from
3693 `GPGDIR/gnupg.nls/LANGID.mo'. Here GPGDIR is the directory out
3694 of which the gpg binary has been loaded. If it can't be loaded
3695 the Registry is tried and as last resort the native Windows
3696 locale system is used.
3700 File: gnupg.info, Node: GPG Examples, Next: Unattended Usage of GPG, Prev: GPG Configuration, Up: Invoking GPG
3705 gpg -se -r `Bob' `file'
3706 sign and encrypt for user Bob
3708 gpg -clearsign `file'
3709 make a clear text signature
3712 make a detached signature
3714 gpg -u 0x12345678 -sb `file'
3715 make a detached signature with the key 0x12345678
3717 gpg -list-keys `user_ID'
3720 gpg -fingerprint `user_ID'
3723 gpg -verify `pgpfile'
3724 gpg -verify `sigfile'
3725 Verify the signature of the file but do not output the data. The
3726 second form is used for detached signatures, where `sigfile' is
3727 the detached signature (either ASCII armored or binary) and are
3728 the signed data; if this is not given, the name of the file
3729 holding the signed data is constructed by cutting off the
3730 extension (".asc" or ".sig") of `sigfile' or by asking the user
3736 The program returns 0 if everything was fine, 1 if at least a signature
3737 was bad, and other error codes for fatal errors.
3742 Use a *good* password for your user account and a *good* passphrase to
3743 protect your secret key. This passphrase is the weakest part of the
3744 whole system. Programs to do dictionary attacks on your secret keyring
3745 are very easy to write and so you should protect your "~/.gnupg/"
3746 directory very well.
3748 Keep in mind that, if this program is used over a network (telnet),
3749 it is *very* easy to spy out your passphrase!
3751 If you are going to verify detached signatures, make sure that the
3752 program knows about it; either give both filenames on the command line
3753 or use `-' to specify STDIN.
3755 INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
3756 ********************************************
3758 GnuPG tries to be a very flexible implementation of the OpenPGP
3759 standard. In particular, GnuPG implements many of the optional parts of
3760 the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
3761 compression algorithms. It is important to be aware that not all
3762 OpenPGP programs implement these optional algorithms and that by
3763 forcing their use via the `--cipher-algo', `--digest-algo',
3764 `--cert-digest-algo', or `--compress-algo' options in GnuPG, it is
3765 possible to create a perfectly valid OpenPGP message, but one that
3766 cannot be read by the intended recipient.
3768 There are dozens of variations of OpenPGP programs available, and
3769 each supports a slightly different subset of these optional algorithms.
3770 For example, until recently, no (unhacked) version of PGP supported the
3771 BLOWFISH cipher algorithm. A message using BLOWFISH simply could not be
3772 read by a PGP user. By default, GnuPG uses the standard OpenPGP
3773 preferences system that will always do the right thing and create
3774 messages that are usable by all recipients, regardless of which OpenPGP
3775 program they use. Only override this safe default if you really know
3778 If you absolutely must override the safe default, or if the
3779 preferences on a given key are invalid for some reason, you are far
3780 better off using the `--pgp6', `--pgp7', or `--pgp8' options. These
3781 options are safe as they do not force any particular algorithms in
3782 violation of OpenPGP, but rather reduce the available algorithms to a
3788 On older systems this program should be installed as setuid(root). This
3789 is necessary to lock memory pages. Locking memory pages prevents the
3790 operating system from writing memory pages (which may contain
3791 passphrases or other sensitive material) to disk. If you get no warning
3792 message about insecure memory your operating system supports locking
3793 without being root. The program drops root privileges as soon as locked
3794 memory is allocated.
3796 Note also that some systems (especially laptops) have the ability to
3797 "suspend to disk" (also known as "safe sleep" or "hibernate"). This
3798 writes all memory to disk before going into a low power or even powered
3799 off mode. Unless measures are taken in the operating system to protect
3800 the saved memory, passphrases or other sensitive material may be
3801 recoverable from it later.
3803 Before you report a bug you should first search the mailing list
3804 archives for similar problems and second check whether such a bug has
3805 already been reported to our bug tracker at http://bugs.gnupg.org .
3808 File: gnupg.info, Node: Unattended Usage of GPG, Prev: GPG Examples, Up: Invoking GPG
3810 3.5 Unattended Usage
3811 ====================
3813 `gpg' is often used as a backend engine by other software. To help
3814 with this a machine interface has been defined to have an unambiguous
3815 way to do this. The options `--status-fd' and `--batch' are almost
3816 always required for this.
3820 * Unattended GPG key generation:: Unattended key generation
3823 File: gnupg.info, Node: Unattended GPG key generation, Up: Unattended Usage of GPG
3825 3.6 Unattended key generation
3826 =============================
3828 The command `--gen-key' may be used along with the option `--batch' for
3829 unattended key generation. The parameters are either read from stdin
3830 or given as a file on the command line. The format of the parameter
3833 * Text only, line length is limited to about 1000 characters.
3835 * UTF-8 encoding must be used to specify non-ASCII characters.
3837 * Empty lines are ignored.
3839 * Leading and trailing while space is ignored.
3841 * A hash sign as the first non white space character indicates a
3844 * Control statements are indicated by a leading percent sign, the
3845 arguments are separated by white space from the keyword.
3847 * Parameters are specified by a keyword, followed by a colon.
3848 Arguments are separated by white space.
3850 * The first parameter must be `Key-Type'; control statements may be
3853 * The order of the parameters does not matter except for `Key-Type'
3854 which must be the first parameter. The parameters are only used
3855 for the generated keyblock (primary and subkeys); parameters
3856 from previous sets are not used. Some syntactically checks may
3859 * Key generation takes place when either the end of the parameter
3860 file is reached, the next `Key-Type' parameter is encountered or
3861 at the control statement `%commit' is encountered.
3866 Print TEXT as diagnostic.
3869 Suppress actual key generation (useful for syntax checking).
3872 Perform the key generation. Note that an implicit commit is done
3873 at the next Key-Type parameter.
3877 Do not write the key to the default or commandline given keyring
3878 but to FILENAME. This must be given before the first commit to
3879 take place, duplicate specification of the same filename is
3880 ignored, the last filename before a commit is used. The filename
3881 is used until a new filename is used (at commit points) and all
3882 keys are written to that file. If a new filename is given, this
3883 file is created (and overwrites an existing one). For GnuPG
3884 versions prior to 2.1, both control statements must be given. For
3885 GnuPG 2.1 and later `%secring' is a no-op.
3889 Enable (or disable) a mode where the command `passphrase' is
3890 ignored and instead the usual passphrase dialog is used. This does
3891 not make sense for batch key generation; however the unattended key
3892 generation feature is also used by GUIs and this feature
3893 relinquishes the GUI from implementing its own passphrase entry
3894 code. These are global control statements and affect all future
3898 Since GnuPG version 2.1 it is not anymore possible to specify a
3899 passphrase for unattended key generation. The passphrase command
3900 is simply ignored and `%ask-passpharse' is thus implicitly enabled.
3901 Using this option allows the creation of keys without any
3902 passphrase protection. This option is mainly intended for
3906 If given the keys are created using a faster and a somewhat less
3907 secure random number generator. This option may be used for keys
3908 which are only used for a short time and do not require full
3909 cryptographic strength. It takes only effect if used together with
3910 the control statement `%no-protection'.
3916 Starts a new parameter block by giving the type of the primary
3917 key. The algorithm must be capable of signing. This is a required
3918 parameter. ALGO may either be an OpenPGP algorithm number or a
3919 string with the algorithm name. The special value `default' may
3920 be used for ALGO to create the default key type; in this case a
3921 `Key-Usage' shall not be given and `default' also be used for
3925 The requested length of the generated key in bits. The default is
3926 returned by running the command `gpg2 --gpgconf-list'.
3929 This is optional and used to generate a CSR or certificate for an
3930 already existing key. Key-Length will be ignored when given.
3932 Key-Usage: USAGE-LIST
3933 Space or comma delimited list of key usages. Allowed values are
3934 `encrypt', `sign', and `auth'. This is used to generate the key
3935 flags. Please make sure that the algorithm is capable of this
3936 usage. Note that OpenPGP requires that all primary keys are
3937 capable of certification, so no matter what usage is given here,
3938 the `cert' flag will be on. If no `Key-Usage' is specified and
3939 the `Key-Type' is not `default', all allowed usages for that
3940 particular algorithm are used; if it is not given but `default' is
3941 used the usage will be `sign'.
3944 This generates a secondary key (subkey). Currently only one subkey
3945 can be handled. See also `Key-Type' above.
3947 Subkey-Length: NBITS
3948 Length of the secondary key (subkey) in bits. The default is
3949 returned by running the command `gpg2 --gpgconf-list'".
3951 Subkey-Usage: USAGE-LIST
3952 Key usage lists for a subkey; similar to `Key-Usage'.
3955 If you want to specify a passphrase for the secret key, enter it
3956 here. Default is not to use any passphrase.
3959 Name-Comment: COMMENT
3961 The three parts of a user name. Remember to use UTF-8 encoding
3962 here. If you don't give any of them, no user ID is created.
3964 Expire-Date: ISO-DATE|(NUMBER[d|w|m|y])
3965 Set the expiration date for the key (and the subkey). It may
3966 either be entered in ISO date format (2000-08-15) or as number of
3967 days, weeks, month or years. The special notation "seconds=N" is
3968 also allowed to directly give an Epoch value. Without a letter
3969 days are assumed. Note that there is no check done on the
3970 overflow of the type used by OpenPGP for timestamps. Thus you
3971 better make sure that the given value make sense. Although
3972 OpenPGP works with time intervals, GnuPG uses an absolute value
3973 internally and thus the last year we can represent is 2105.
3975 Ceation-Date: ISO-DATE
3976 Set the creation date of the key as stored in the key information
3977 and which is also part of the fingerprint calculation. Either a
3978 date like "1986-04-26" or a full timestamp like "19860426T042640"
3979 may be used. The time is considered to be UTC. If it is not
3980 given the current time is used.
3983 Set the cipher, hash, and compression preference values for this
3984 key. This expects the same type of string as the sub-command
3985 `setpref' in the `--edit-key' menu.
3987 Revoker: ALGO:FPR [sensitive]
3988 Add a designated revoker to the generated key. Algo is the public
3989 key algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.)
3990 FPR is the fingerprint of the designated revoker. The optional
3991 `sensitive' flag marks the designated revoker as sensitive
3992 information. Only v4 keys may be designated revokers.
3995 This is an optional parameter that specifies the preferred
3996 keyserver URL for the key.
3999 This is an optional parameter only used with the status lines
4000 KEY_CREATED and KEY_NOT_CREATED. STRING may be up to 100
4001 characters and should not contain spaces. It is useful for batch
4002 key generation to associate a key parameter block with a status
4006 Here is an example on how to create a key:
4008 %echo Generating a basic OpenPGP key
4013 Name-Real: Joe Tester
4014 Name-Comment: with stupid passphrase
4015 Name-Email: joe@foo.bar
4020 # Do a commit here, so that we can later print "done" :-)
4024 $ gpg2 --batch --gen-key foo
4026 $ gpg2 --no-default-keyring --secret-keyring ./foo.sec \
4027 --keyring ./foo.pub --list-secret-keys
4028 /home/wk/work/gnupg-stable/scratch/foo.sec
4029 ------------------------------------------
4030 sec 1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@foo.bar>
4031 ssb 1024g/8F70E2C0 2000-03-09
4033 If you want to create a key with the default algorithms you would use
4035 %echo Generating a default key
4037 Subkey-Type: default
4038 Name-Real: Joe Tester
4039 Name-Comment: with stupid passphrase
4040 Name-Email: joe@foo.bar
4045 # Do a commit here, so that we can later print "done" :-)
4050 File: gnupg.info, Node: Invoking GPGSM, Next: Invoking SCDAEMON, Prev: Invoking GPG, Up: Top
4055 `gpgsm' is a tool similar to `gpg' to provide digital encryption and
4056 signing services on X.509 certificates and the CMS protocol. It is
4057 mainly used as a backend for S/MIME mail processing. `gpgsm' includes
4058 a full featured certificate management and complies with all rules
4059 defined for the German Sphinx project.
4061 *Note Option Index::, for an index to `GPGSM''s commands and options.
4065 * GPGSM Commands:: List of all commands.
4066 * GPGSM Options:: List of all options.
4067 * GPGSM Configuration:: Configuration files.
4068 * GPGSM Examples:: Some usage examples.
4070 Developer information:
4071 * Unattended Usage:: Using `gpgsm' from other programs.
4072 * GPGSM Protocol:: The protocol the server mode uses.
4075 File: gnupg.info, Node: GPGSM Commands, Next: GPGSM Options, Up: Invoking GPGSM
4080 Commands are not distinguished from options except for the fact that
4081 only one command is allowed.
4085 * General GPGSM Commands:: Commands not specific to the functionality.
4086 * Operational GPGSM Commands:: Commands to select the type of operation.
4087 * Certificate Management:: How to manage certificates.
4090 File: gnupg.info, Node: General GPGSM Commands, Next: Operational GPGSM Commands, Up: GPGSM Commands
4092 4.1.1 Commands not specific to the function
4093 -------------------------------------------
4096 Print the program version and licensing information. Note that you
4097 cannot abbreviate this command.
4100 Print a usage message summarizing the most useful command-line
4101 options. Note that you cannot abbreviate this command.
4104 Print warranty information. Note that you cannot abbreviate this
4108 Print a list of all available options and commands. Note that you
4109 cannot abbreviate this command.
4112 File: gnupg.info, Node: Operational GPGSM Commands, Next: Certificate Management, Prev: General GPGSM Commands, Up: GPGSM Commands
4114 4.1.2 Commands to select the type of operation
4115 ----------------------------------------------
4118 Perform an encryption. The keys the data is encrypted too must be
4119 set using the option `--recipient'.
4122 Perform a decryption; the type of input is automatically
4123 determined. It may either be in binary form or PEM encoded;
4124 automatic determination of base-64 encoding is not done.
4127 Create a digital signature. The key used is either the fist one
4128 found in the keybox or those set with the `--local-user' option.
4131 Check a signature file for validity. Depending on the arguments a
4132 detached signature may also be checked.
4135 Run in server mode and wait for commands on the `stdin'.
4137 `--call-dirmngr COMMAND [ARGS]'
4138 Behave as a Dirmngr client issuing the request COMMAND with the
4139 optional list of ARGS. The output of the Dirmngr is printed
4140 stdout. Please note that file names given as arguments should
4141 have an absolute file name (i.e. commencing with `/' because they
4142 are passed verbatim to the Dirmngr and the working directory of the
4143 Dirmngr might not be the same as the one of this client.
4144 Currently it is not possible to pass data via stdin to the
4145 Dirmngr. COMMAND should not contain spaces.
4147 This is command is required for certain maintaining tasks of the
4148 dirmngr where a dirmngr must be able to call back to `gpgsm'. See
4149 the Dirmngr manual for details.
4151 `--call-protect-tool ARGUMENTS'
4152 Certain maintenance operations are done by an external program call
4153 `gpg-protect-tool'; this is usually not installed in a directory
4154 listed in the PATH variable. This command provides a simple
4155 wrapper to access this tool. ARGUMENTS are passed verbatim to
4156 this command; use `--help' to get a list of supported operations.
4160 File: gnupg.info, Node: Certificate Management, Prev: Operational GPGSM Commands, Up: GPGSM Commands
4162 4.1.3 How to manage the certificates and keys
4163 ---------------------------------------------
4166 -This command allows the creation of a certificate signing
4167 request. It -is commonly used along with the `--output' option to
4168 save the -created CSR into a file. If used with the `--batch' a
4169 parameter -file is used to create the CSR.
4173 List all available certificates stored in the local key database.
4174 Note that the displayed data might be reformatted for better human
4175 readability and illegal characters are replaced by safe
4178 `--list-secret-keys'
4180 List all available certificates for which a corresponding a secret
4183 `--list-external-keys PATTERN'
4184 List certificates matching PATTERN using an external server. This
4185 utilizes the `dirmngr' service.
4188 Same as `--list-keys' but also prints all keys making up the chain.
4192 List all available certificates stored in the local key database
4193 using a format useful mainly for debugging.
4196 Same as `--dump-keys' but also prints all keys making up the chain.
4198 `--dump-secret-keys'
4199 List all available certificates for which a corresponding a secret
4200 key is available using a format useful mainly for debugging.
4202 `--dump-external-keys PATTERN'
4203 List certificates matching PATTERN using an external server. This
4204 utilizes the `dirmngr' service. It uses a format useful mainly
4207 `--keydb-clear-some-cert-flags'
4208 This is a debugging aid to reset certain flags in the key database
4209 which are used to cache certain certificate stati. It is
4210 especially useful if a bad CRL or a weird running OCSP responder
4211 did accidentally revoke certificate. There is no security issue
4212 with this command because `gpgsm' always make sure that the
4213 validity of a certificate is checked right before it is used.
4215 `--delete-keys PATTERN'
4216 Delete the keys matching PATTERN. Note that there is no command
4217 to delete the secret part of the key directly. In case you need
4218 to do this, you should run the command `gpgsm --dump-secret-keys
4219 KEYID' before you delete the key, copy the string of hex-digits in
4220 the "keygrip" line and delete the file consisting of these
4221 hex-digits and the suffix `.key' from the `private-keys-v1.d'
4222 directory below our GnuPG home directory (usually `~/.gnupg').
4224 `--export [PATTERN]'
4225 Export all certificates stored in the Keybox or those specified by
4226 the optional PATTERN. Those pattern consist of a list of user ids
4227 (*note how-to-specify-a-user-id::). When used along with the
4228 `--armor' option a few informational lines are prepended before
4229 each block. There is one limitation: As there is no commonly
4230 agreed upon way to pack more than one certificate into an ASN.1
4231 structure, the binary export (i.e. without using `armor') works
4232 only for the export of one certificate. Thus it is required to
4233 specify a PATTERN which yields exactly one certificate. Ephemeral
4234 certificate are only exported if all PATTERN are given as
4235 fingerprints or keygrips.
4237 `--export-secret-key-p12 KEY-ID'
4238 Export the private key and the certificate identified by KEY-ID in
4239 a PKCS#12 format. When using along with the `--armor' option a few
4240 informational lines are prepended to the output. Note, that the
4241 PKCS#12 format is not very secure and this command is only
4242 provided if there is no other way to exchange the private key.
4243 (*note option --p12-charset::)
4246 Import the certificates from the PEM or binary encoded files as
4247 well as from signed-only messages. This command may also be used
4248 to import a secret key from a PKCS#12 file.
4251 Read information about the private keys from the smartcard and
4252 import the certificates from there. This command utilizes the
4253 `gpg-agent' and in turn the `scdaemon'.
4256 Change the passphrase of the private key belonging to the
4257 certificate specified as USER_ID. Note, that changing the
4258 passphrase/PIN of a smartcard is not yet supported.
4262 File: gnupg.info, Node: GPGSM Options, Next: GPGSM Configuration, Prev: GPGSM Commands, Up: Invoking GPGSM
4267 `GPGSM' features a bunch of options to control the exact behaviour and
4268 to change the default configuration.
4272 * Configuration Options:: How to change the configuration.
4273 * Certificate Options:: Certificate related options.
4274 * Input and Output:: Input and Output.
4275 * CMS Options:: How to change how the CMS is created.
4276 * Esoteric Options:: Doing things one usually do not want to do.
4279 File: gnupg.info, Node: Configuration Options, Next: Certificate Options, Up: GPGSM Options
4281 4.2.1 How to change the configuration
4282 -------------------------------------
4284 These options are used to change the configuration and are usually found
4288 Reads configuration from FILE instead of from the default per-user
4289 configuration file. The default configuration file is named
4290 `gpgsm.conf' and expected in the `.gnupg' directory directly below
4291 the home directory of the user.
4294 Set the name of the home directory to DIR. If this option is not
4295 used, the home directory defaults to `~/.gnupg'. It is only
4296 recognized when given on the command line. It also overrides any
4297 home directory stated through the environment variable `GNUPGHOME'
4298 or (on W32 systems) by means of the Registry entry
4299 HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
4304 Outputs additional information while running. You can increase
4305 the verbosity by giving several verbose commands to `gpgsm', such
4308 `--policy-file FILENAME'
4309 Change the default name of the policy file to FILENAME.
4311 `--agent-program FILE'
4312 Specify an agent program to be used for secret key operations. The
4313 default value is the `/usr/local/bin/gpg-agent'. This is only used
4314 as a fallback when the environment variable `GPG_AGENT_INFO' is not
4315 set or a running agent cannot be connected.
4317 `--dirmngr-program FILE'
4318 Specify a dirmngr program to be used for CRL checks. The default
4319 value is `/usr/sbin/dirmngr'. This is only used as a fallback
4320 when the environment variable `DIRMNGR_INFO' is not set or a
4321 running dirmngr cannot be connected.
4323 `--prefer-system-dirmngr'
4324 If a system wide `dirmngr' is running in daemon mode, first try to
4325 connect to this one. Fallback to a pipe based server if this does
4326 not work. Under Windows this option is ignored because the system
4327 dirmngr is always used.
4330 Entirely disable the use of the Dirmngr.
4332 `--no-secmem-warning'
4333 Do not print a warning when the so called "secure memory" cannot
4337 When running in server mode, append all logging output to FILE.
4341 File: gnupg.info, Node: Certificate Options, Next: Input and Output, Prev: Configuration Options, Up: GPGSM Options
4343 4.2.2 Certificate related options
4344 ---------------------------------
4346 `--enable-policy-checks'
4347 `--disable-policy-checks'
4348 By default policy checks are enabled. These options may be used to
4351 `--enable-crl-checks'
4352 `--disable-crl-checks'
4353 By default the CRL checks are enabled and the DirMngr is used to
4354 check for revoked certificates. The disable option is most useful
4355 with an off-line network connection to suppress this check.
4357 `--enable-trusted-cert-crl-check'
4358 `--disable-trusted-cert-crl-check'
4359 By default the CRL for trusted root certificates are checked like
4360 for any other certificates. This allows a CA to revoke its own
4361 certificates voluntary without the need of putting all ever issued
4362 certificates into a CRL. The disable option may be used to switch
4363 this extra check off. Due to the caching done by the Dirmngr,
4364 there will not be any noticeable performance gain. Note, that
4365 this also disables possible OCSP checks for trusted root
4366 certificates. A more specific way of disabling this check is by
4367 adding the "relax" keyword to the root CA line of the
4370 `--force-crl-refresh'
4371 Tell the dirmngr to reload the CRL for each request. For better
4372 performance, the dirmngr will actually optimize this by suppressing
4373 the loading for short time intervals (e.g. 30 minutes). This option
4374 is useful to make sure that a fresh CRL is available for
4375 certificates hold in the keybox. The suggested way of doing this
4376 is by using it along with the option `--with-validation' for a key
4377 listing command. This option should not be used in a
4382 By default OCSP checks are disabled. The enable option may be
4383 used to enable OCSP checks via Dirmngr. If CRL checks are also
4384 enabled, CRLs will be used as a fallback if for some reason an
4385 OCSP request will not succeed. Note, that you have to allow OCSP
4386 requests in Dirmngr's configuration too (option `--allow-ocsp')
4387 and configure Dirmngr properly. If you do not do so you will get
4388 the error code `Not supported'.
4390 `--auto-issuer-key-retrieve'
4391 If a required certificate is missing while validating the chain of
4392 certificates, try to load that certificate from an external
4393 location. This usually means that Dirmngr is employed to search
4394 for the certificate. Note that this option makes a "web bug" like
4395 behavior possible. LDAP server operators can see which keys you
4396 request, so by sending you a message signed by a brand new key
4397 (which you naturally will not have on your local keybox), the
4398 operator can tell both your IP address and the time when you
4399 verified the signature.
4401 `--validation-model NAME'
4402 This option changes the default validation model. The only
4403 possible values are "shell" (which is the default), "chain" which
4404 forces the use of the chain model and "steed" for a new simplified
4405 model. The chain model is also used if an option in the
4406 `trustlist.txt' or an attribute of the certificate requests it.
4407 However the standard model (shell) is in that case always tried
4410 `--ignore-cert-extension OID'
4411 Add OID to the list of ignored certificate extensions. The OID is
4412 expected to be in dotted decimal form, like `2.5.29.3'. This
4413 option may be used more than once. Critical flagged certificate
4414 extensions matching one of the OIDs in the list are treated as if
4415 they are actually handled and thus the certificate will not be
4416 rejected due to an unknown critical extension. Use this option
4417 with care because extensions are usually flagged as critical for a
4422 File: gnupg.info, Node: Input and Output, Next: CMS Options, Prev: Certificate Options, Up: GPGSM Options
4424 4.2.3 Input and Output
4425 ----------------------
4429 Create PEM encoded output. Default is binary output.
4432 Create Base-64 encoded output; i.e. PEM without the header lines.
4435 Assume the input data is PEM encoded. Default is to autodetect the
4436 encoding but this is may fail.
4439 Assume the input data is plain base-64 encoded.
4442 Assume the input data is binary encoded.
4444 `--p12-charset NAME'
4445 `gpgsm' uses the UTF-8 encoding when encoding passphrases for
4446 PKCS#12 files. This option may be used to force the passphrase to
4447 be encoded in the specified encoding NAME. This is useful if the
4448 application used to import the key uses a different encoding and
4449 thus will not be able to import a file generated by `gpgsm'.
4450 Commonly used values for NAME are `Latin1' and `CP850'. Note that
4451 `gpgsm' itself automagically imports any file with a passphrase
4452 encoded to the most commonly used encodings.
4454 `--default-key USER_ID'
4455 Use USER_ID as the standard key for signing. This key is used if
4456 no other key has been defined as a signing key. Note, that the
4457 first `--local-users' option also sets this key if it has not yet
4458 been set; however `--default-key' always overrides this.
4460 `--local-user USER_ID'
4463 Set the user(s) to be used for signing. The default is the first
4464 secret key found in the database.
4468 Encrypt to the user id NAME. There are several ways a user id may
4469 be given (*note how-to-specify-a-user-id::).
4473 Write output to FILE. The default is to write it to stdout.
4476 Displays extra information with the `--list-keys' commands.
4477 Especially a line tagged `grp' is printed which tells you the
4478 keygrip of a key. This string is for example used as the file
4479 name of the secret key.
4482 When doing a key listing, do a full validation check for each key
4483 and print the result. This is usually a slow operation because it
4484 requires a CRL lookup and other operations.
4486 When used along with -import, a validation of the certificate to
4487 import is done and only imported if it succeeds the test. Note
4488 that this does not affect an already available certificate in the
4489 DB. This option is therefore useful to simply verify a
4492 `--with-md5-fingerprint'
4493 For standard key listings, also print the MD5 fingerprint of the
4497 Include the keygrip in standard key listings. Note that the
4498 keygrip is always listed in -with-colons mode.
4502 File: gnupg.info, Node: CMS Options, Next: Esoteric Options, Prev: Input and Output, Up: GPGSM Options
4504 4.2.4 How to change how the CMS is created.
4505 -------------------------------------------
4508 Using N of -2 includes all certificate except for the root cert,
4509 -1 includes all certs, 0 does not include any certs, 1 includes
4510 only the signers cert and all other positive values include up to N
4511 certificates starting with the signer cert. The default is -2.
4514 Use the cipher algorithm with the ASN.1 object identifier OID for
4515 encryption. For convenience the strings `3DES', `AES' and
4516 `AES256' may be used instead of their OIDs. The default is `3DES'
4517 (1.2.840.113549.3.7).
4519 `--digest-algo `name''
4520 Use `name' as the message digest algorithm. Usually this
4521 algorithm is deduced from the respective signing certificate. This
4522 option forces the use of the given algorithm and may lead to severe
4523 interoperability problems.
4527 File: gnupg.info, Node: Esoteric Options, Prev: CMS Options, Up: GPGSM Options
4529 4.2.5 Doing things one usually do not want to do.
4530 -------------------------------------------------
4532 `--extra-digest-algo NAME'
4533 Sometimes signatures are broken in that they announce a different
4534 digest algorithm than actually used. `gpgsm' uses a one-pass data
4535 processing model and thus needs to rely on the announced digest
4536 algorithms to properly hash the data. As a workaround this option
4537 may be used to tell gpg to also hash the data using the algorithm
4538 NAME; this slows processing down a little bit but allows to verify
4539 such broken signatures. If `gpgsm' prints an error like "digest
4540 algo 8 has not been enabled" you may want to try this option, with
4543 `--faked-system-time EPOCH'
4544 This option is only useful for testing; it sets the system time
4545 back or forth to EPOCH which is the number of seconds elapsed
4546 since the year 1970. Alternatively EPOCH may be given as a full
4547 ISO time string (e.g. "20070924T154812").
4549 `--with-ephemeral-keys'
4550 Include ephemeral flagged keys in the output of key listings. Note
4551 that they are included anyway if the key specification for a
4552 listing is given as fingerprint or keygrip.
4554 `--debug-level LEVEL'
4555 Select the debug level for investigating problems. LEVEL may be a
4556 numeric value or by a keyword:
4559 No debugging at all. A value of less than 1 may be used
4560 instead of the keyword.
4563 Some basic debug messages. A value between 1 and 2 may be
4564 used instead of the keyword.
4567 More verbose debug messages. A value between 3 and 5 may be
4568 used instead of the keyword.
4571 Even more detailed messages. A value between 6 and 8 may be
4572 used instead of the keyword.
4575 All of the debug messages you can get. A value greater than 8
4576 may be used instead of the keyword. The creation of hash
4577 tracing files is only enabled if the keyword is used.
4579 How these messages are mapped to the actual debugging flags is not
4580 specified and may change with newer releases of this program. They
4581 are however carefully selected to best aid in debugging.
4584 This option is only useful for debugging and the behaviour may
4585 change at any time without notice; using `--debug-levels' is the
4586 preferred method to select the debug verbosity. FLAGS are bit
4587 encoded and may be given in usual C-Syntax. The currently defined
4591 X.509 or OpenPGP protocol related data
4594 values of big number integers
4597 low level crypto operations
4606 show memory statistics.
4609 write hashed data to files named `dbgmd-000*'
4612 trace Assuan protocol
4614 Note, that all flags set using this option may get overridden by
4618 Same as `--debug=0xffffffff'
4620 `--debug-allow-core-dump'
4621 Usually `gpgsm' tries to avoid dumping core by well written code
4622 and by disabling core dumps for security reasons. However, bugs
4623 are pretty durable beasts and to squash them it is sometimes
4624 useful to have a core dump. This option enables core dumps unless
4625 the Bad Thing happened before the option parsing.
4627 `--debug-no-chain-validation'
4628 This is actually not a debugging option but only useful as such.
4629 It lets `gpgsm' bypass all certificate chain validation checks.
4631 `--debug-ignore-expiration'
4632 This is actually not a debugging option but only useful as such.
4633 It lets `gpgsm' ignore all notAfter dates, this is used by the
4636 `--fixed-passphrase STRING'
4637 Supply the passphrase STRING to the gpg-protect-tool. This option
4638 is only useful for the regression tests included with this package
4639 and may be revised or removed at any time without notice.
4641 `--no-common-certs-import'
4642 Suppress the import of common certificates on keybox creation.
4645 All the long options may also be given in the configuration file
4646 after stripping off the two leading dashes.
4649 File: gnupg.info, Node: GPGSM Configuration, Next: GPGSM Examples, Prev: GPGSM Options, Up: Invoking GPGSM
4651 4.3 Configuration files
4652 =======================
4654 There are a few configuration files to control certain aspects of
4655 `gpgsm''s operation. Unless noted, they are expected in the current
4656 home directory (*note option --homedir::).
4659 This is the standard configuration file read by `gpgsm' on
4660 startup. It may contain any valid long option; the leading two
4661 dashes may not be entered and the option may not be abbreviated.
4662 This default name may be changed on the command line (*note option
4663 --options::). You should backup this file.
4666 This is a list of allowed CA policies. This file should list the
4667 object identifiers of the policies line by line. Empty lines and
4668 lines starting with a hash mark are ignored. Policies missing in
4669 this file and not marked as critical in the certificate will print
4670 only a warning; certificates with policies marked as critical and
4671 not listed in this file will fail the signature verification. You
4672 should backup this file.
4674 For example, to allow only the policy 2.289.9.9, the file should
4681 This is the list of root certificates used for qualified
4682 certificates. They are defined as certificates capable of
4683 creating legally binding signatures in the same way as handwritten
4684 signatures are. Comments start with a hash mark and empty lines
4685 are ignored. Lines do have a length limit but this is not a
4686 serious limitation as the format of the entries is fixed and
4687 checked by gpgsm: A non-comment line starts with optional
4688 whitespace, followed by exactly 40 hex character, white space and
4689 a lowercased 2 letter country code. Additional data delimited with
4690 by a white space is current ignored but might late be used for
4693 Note that even if a certificate is listed in this file, this does
4694 not mean that the certificate is trusted; in general the
4695 certificates listed in this file need to be listed also in
4698 This is a global file an installed in the data directory (e.g.
4699 `/usr/share/gnupg/qualified.txt'). GnuPG installs a suitable file
4700 with root certificates as used in Germany. As new Root-CA
4701 certificates may be issued over time, these entries may need to be
4702 updated; new distributions of this software should come with an
4703 updated list but it is still the responsibility of the
4704 Administrator to check that this list is correct.
4706 Everytime `gpgsm' uses a certificate for signing or verification
4707 this file will be consulted to check whether the certificate under
4708 question has ultimately been issued by one of these CAs. If this
4709 is the case the user will be informed that the verified signature
4710 represents a legally binding ("qualified") signature. When
4711 creating a signature using such a certificate an extra prompt will
4712 be issued to let the user confirm that such a legally binding
4713 signature shall really be created.
4715 Because this software has not yet been approved for use with such
4716 certificates, appropriate notices will be shown to indicate this
4720 This is plain text file with a few help entries used with
4721 `pinentry' as well as a large list of help items for `gpg' and
4722 `gpgsm'. The standard file has English help texts; to install
4723 localized versions use filenames like `help.LL.txt' with LL
4724 denoting the locale. GnuPG comes with a set of predefined help
4725 files in the data directory (e.g. `/usr/share/gnupg/help.de.txt')
4726 and allows overriding of any help item by help files stored in the
4727 system configuration directory (e.g. `/etc/gnupg/help.de.txt').
4728 For a reference of the help file's syntax, please see the installed
4732 This file is a collection of common certificates used to populated
4733 a newly created `pubring.kbx'. An administrator may replace this
4734 file with a custom one. The format is a concatenation of PEM
4735 encoded X.509 certificates. This global file is installed in the
4736 data directory (e.g. `/usr/share/gnupg/com-certs.pem').
4739 Note that on larger installations, it is useful to put predefined
4740 files into the directory `/etc/skel/.gnupg/' so that newly created users
4741 start up with a working configuration. For existing users a small
4742 helper script is provided to create these files (*note addgnupghome::).
4744 For internal purposes gpgsm creates and maintains a few other files;
4745 they all live in in the current home directory (*note option
4746 --homedir::). Only `gpgsm' may modify these files.
4749 This a database file storing the certificates as well as meta
4750 information. For debugging purposes the tool `kbxutil' may be
4751 used to show the internal structure of this file. You should
4755 This content of this file is used to maintain the internal state
4756 of the random number generator across invocations. The same file
4757 is used by other programs of this software too.
4760 If this file exists and the environment variable `GPG_AGENT_INFO'
4761 is not set, `gpgsm' will first try to connect to this socket for
4762 accessing `gpg-agent' before starting a new `gpg-agent' instance.
4763 Under Windows this socket (which in reality be a plain file
4764 describing a regular TCP listening port) is the standard way of
4765 connecting the `gpg-agent'.
4769 File: gnupg.info, Node: GPGSM Examples, Next: Unattended Usage, Prev: GPGSM Configuration, Up: Invoking GPGSM
4774 $ gpgsm -er goo@bar.net <plaintext >ciphertext
4777 File: gnupg.info, Node: Unattended Usage, Next: GPGSM Protocol, Prev: GPGSM Examples, Up: Invoking GPGSM
4779 4.5 Unattended Usage
4780 ====================
4782 `gpgsm' is often used as a backend engine by other software. To help
4783 with this a machine interface has been defined to have an unambiguous
4784 way to do this. This is most likely used with the `--server' command
4785 but may also be used in the standard operation mode by using the
4786 `--status-fd' option.
4790 * Automated signature checking:: Automated signature checking.
4791 * CSR and certificate creation:: CSR and certificate creation.
4794 File: gnupg.info, Node: Automated signature checking, Up: Unattended Usage
4796 4.6 Automated signature checking
4797 ================================
4799 It is very important to understand the semantics used with signature
4800 verification. Checking a signature is not as simple as it may sound and
4801 so the operation is a bit complicated. In most cases it is required to
4802 look at several status lines. Here is a table of all cases a signed
4805 The signature is valid
4806 This does mean that the signature has been successfully verified,
4807 the certificates are all sane. However there are two subcases with
4808 important information: One of the certificates may have expired
4809 or a signature of a message itself as expired. It is a sound
4810 practise to consider such a signature still as valid but
4811 additional information should be displayed. Depending on the
4812 subcase `gpgsm' will issue these status codes:
4813 signature valid and nothing did expire
4814 `GOODSIG', `VALIDSIG', `TRUST_FULLY'
4816 signature valid but at least one certificate has expired
4817 `EXPKEYSIG', `VALIDSIG', `TRUST_FULLY'
4819 signature valid but expired
4820 `EXPSIG', `VALIDSIG', `TRUST_FULLY' Note, that this case is
4821 currently not implemented.
4823 The signature is invalid
4824 This means that the signature verification failed (this is an
4825 indication of af a transfer error, a program error or tampering
4826 with the message). `gpgsm' issues one of these status codes
4830 ``GOODSIG', `VALIDSIG' `TRUST_NEVER''
4832 Error verifying a signature
4833 For some reason the signature could not be verified, i.e. it
4834 cannot be decided whether the signature is valid or invalid. A
4835 common reason for this is a missing certificate.
4839 File: gnupg.info, Node: CSR and certificate creation, Up: Unattended Usage
4841 4.7 CSR and certificate creation
4842 ================================
4844 *Please notice*: The immediate creation of certificates is only
4845 supported by GnuPG version 2.1 or later. With a 2.0 version you may
4848 The command `--gen-key' may be used along with the option `--batch' to
4849 either create a certificate signing request (CSR) or an X.509
4850 certificate. The is controlled by a parameter file; the format of this
4853 * Text only, line length is limited to about 1000 characters.
4855 * UTF-8 encoding must be used to specify non-ASCII characters.
4857 * Empty lines are ignored.
4859 * Leading and trailing while space is ignored.
4861 * A hash sign as the first non white space character indicates a
4864 * Control statements are indicated by a leading percent sign, the
4865 arguments are separated by white space from the keyword.
4867 * Parameters are specified by a keyword, followed by a colon.
4868 Arguments are separated by white space.
4870 * The first parameter must be `Key-Type', control statements may be
4873 * The order of the parameters does not matter except for `Key-Type'
4874 which must be the first parameter. The parameters are only used
4875 for the generated CSR/certificate; parameters from previous sets
4876 are not used. Some syntactically checks may be performed.
4878 * Key generation takes place when either the end of the parameter
4879 file is reached, the next `Key-Type' parameter is encountered or
4880 at the control statement `%commit' is encountered.
4885 Print TEXT as diagnostic.
4888 Suppress actual key generation (useful for syntax checking).
4891 Perform the key generation. Note that an implicit commit is done
4892 at the next Key-Type parameter.
4898 Starts a new parameter block by giving the type of the primary
4899 key. The algorithm must be capable of signing. This is a required
4900 parameter. The only supported value for ALGO is `rsa'.
4903 The requested length of a generated key in bits. Defaults to 2048.
4906 This is optional and used to generate a CSR or certificatet for an
4907 already existing key. Key-Length will be ignored when given.
4909 Key-Usage: USAGE-LIST
4910 Space or comma delimited list of key usage, allowed values are
4911 `encrypt', `sign' and `cert'. This is used to generate the
4912 keyUsage extension. Please make sure that the algorithm is
4913 capable of this usage. Default is to allow encrypt and sign.
4915 Name-DN: SUBJECT-NAME
4916 This is the Distinguished Name (DN) of the subject in RFC-2253
4920 This is an email address for the altSubjectName. This parameter is
4921 optional but may occur several times to add several email
4922 addresses to a certificate.
4925 The is an DNS name for the altSubjectName. This parameter is
4926 optional but may occur several times to add several DNS names to a
4930 This is an URI for the altSubjectName. This parameter is optional
4931 but may occur several times to add several URIs to a certificate.
4933 Additional parameters used to create a certificate (in contrast to a
4934 certificate signing request):
4937 If this parameter is given an X.509 certificate will be generated.
4938 SN is expected to be a hex string representing an unsigned integer
4939 of arbitary length. The special value `random' can be used to
4940 create a 64 bit random serial number.
4942 Issuer-DN: ISSUER-NAME
4943 This is the DN name of the issuer in rfc2253 format. If it is not
4944 set it will default to the subject DN and a special GnuPG
4945 extension will be included in the certificate to mark it as a
4946 standalone certificate.
4948 Creation-Date: ISO-DATE
4949 Not-Before: ISO-DATE
4950 Set the notBefore date of the certificate. Either a date like
4951 `1986-04-26' or `1986-04-26 12:00' or a standard ISO timestamp
4952 like `19860426T042640' may be used. The time is considered to be
4953 UTC. If it is not given the current date is used.
4955 Expire-Date: ISO-DATE
4957 Set the notAfter date of the certificate. Either a date like
4958 `2063-04-05' or `2063-04-05 17:00' or a standard ISO timestamp
4959 like `20630405T170000' may be used. The time is considered to be
4960 UTC. If it is not given a default value in the not too far future
4963 Signing-Key: KEYGRIP
4964 This gives the keygrip of the key used to sign the certificate.
4965 If it is not given a self-signed certificate will be created. For
4966 compatibility with future versions, it is suggested to prefix the
4969 Hash-Algo: HASH-ALGO
4970 Use HASH-ALGO for this CSR or certificate. The supported hash
4971 algorithms are: `sha1', `sha256', `sha384' and `sha512'; they may
4972 also be specified with uppercase letters. The default is `sha1'.
4976 File: gnupg.info, Node: GPGSM Protocol, Prev: Unattended Usage, Up: Invoking GPGSM
4978 4.8 The Protocol the Server Mode Uses.
4979 ======================================
4981 Description of the protocol used to access `GPGSM'. `GPGSM' does
4982 implement the Assuan protocol and in addition provides a regular
4983 command line interface which exhibits a full client to this protocol
4984 (but uses internal linking). To start `gpgsm' as a server the command
4985 line the option `--server' must be used. Additional options are
4986 provided to select the communication method (i.e. the name of the
4989 We assume that the connection has already been established; see the
4990 Assuan manual for details.
4994 * GPGSM ENCRYPT:: Encrypting a message.
4995 * GPGSM DECRYPT:: Decrypting a message.
4996 * GPGSM SIGN:: Signing a message.
4997 * GPGSM VERIFY:: Verifying a message.
4998 * GPGSM GENKEY:: Generating a key.
4999 * GPGSM LISTKEYS:: List available keys.
5000 * GPGSM EXPORT:: Export certificates.
5001 * GPGSM IMPORT:: Import certificates.
5002 * GPGSM DELETE:: Delete certificates.
5003 * GPGSM GETINFO:: Information about the process
5006 File: gnupg.info, Node: GPGSM ENCRYPT, Next: GPGSM DECRYPT, Up: GPGSM Protocol
5008 4.8.1 Encrypting a Message
5009 --------------------------
5011 Before encryption can be done the recipient must be set using the
5016 Set the recipient for the encryption. USERID should be the internal
5017 representation of the key; the server may accept any other way of
5018 specification. If this is a valid and trusted recipient the server
5019 does respond with OK, otherwise the return is an ERR with the reason why
5020 the recipient cannot be used, the encryption will then not be done for
5021 this recipient. If the policy is not to encrypt at all if not all
5022 recipients are valid, the client has to take care of this. All
5023 `RECIPIENT' commands are cumulative until a `RESET' or an successful
5026 INPUT FD[=N] [--armor|--base64|--binary]
5028 Set the file descriptor for the message to be encrypted to N.
5029 Obviously the pipe must be open at that point, the server establishes
5030 its own end. If the server returns an error the client should consider
5031 this session failed. If N is not given, this commands uses the last
5032 file descriptor passed to the application. *Note the assuan_sendfd
5033 function: (assuan)fun-assuan_sendfd, on how to do descriptor passing.
5035 The `--armor' option may be used to advice the server that the input
5036 data is in PEM format, `--base64' advices that a raw base-64 encoding
5037 is used, `--binary' advices of raw binary input (BER). If none of
5038 these options is used, the server tries to figure out the used
5039 encoding, but this may not always be correct.
5041 OUTPUT FD[=N] [--armor|--base64]
5043 Set the file descriptor to be used for the output (i.e. the encrypted
5044 message). Obviously the pipe must be open at that point, the server
5045 establishes its own end. If the server returns an error he client
5046 should consider this session failed.
5048 The option armor encodes the output in PEM format, the `--base64'
5049 option applies just a base 64 encoding. No option creates binary
5052 The actual encryption is done using the command
5056 It takes the plaintext from the `INPUT' command, writes to the
5057 ciphertext to the file descriptor set with the `OUTPUT' command, take
5058 the recipients from all the recipients set so far. If this command
5059 fails the clients should try to delete all output currently done or
5060 otherwise mark it as invalid. `GPGSM' does ensure that there will not
5061 be any security problem with leftover data on the output in this case.
5063 This command should in general not fail, as all necessary checks have
5064 been done while setting the recipients. The input and output pipes are
5068 File: gnupg.info, Node: GPGSM DECRYPT, Next: GPGSM SIGN, Prev: GPGSM ENCRYPT, Up: GPGSM Protocol
5070 4.8.2 Decrypting a message
5071 --------------------------
5073 Input and output FDs are set the same way as in encryption, but `INPUT'
5074 refers to the ciphertext and output to the plaintext. There is no need
5075 to set recipients. `GPGSM' automatically strips any S/MIME headers
5076 from the input, so it is valid to pass an entire MIME part to the INPUT
5079 The encryption is done by using the command
5083 It performs the decrypt operation after doing some check on the
5084 internal state. (e.g. that all needed data has been set). Because it
5085 utilizes the GPG-Agent for the session key decryption, there is no need
5086 to ask the client for a protecting passphrase - GpgAgent takes care of
5087 this by requesting this from the user.
5090 File: gnupg.info, Node: GPGSM SIGN, Next: GPGSM VERIFY, Prev: GPGSM DECRYPT, Up: GPGSM Protocol
5092 4.8.3 Signing a Message
5093 -----------------------
5095 Signing is usually done with these commands:
5097 INPUT FD[=N] [--armor|--base64|--binary]
5099 This tells `GPGSM' to read the data to sign from file descriptor N.
5101 OUTPUT FD[=M] [--armor|--base64]
5103 Write the output to file descriptor M. If a detached signature is
5104 requested, only the signature is written.
5108 Sign the data set with the INPUT command and write it to the sink
5109 set by OUTPUT. With `--detached', a detached signature is created
5112 The key used for signing is the default one or the one specified in
5113 the configuration file. To get finer control over the keys, it is
5114 possible to use the command
5118 to the signer's key. USERID should be the internal representation
5119 of the key; the server may accept any other way of specification. If
5120 this is a valid and trusted recipient the server does respond with OK,
5121 otherwise the return is an ERR with the reason why the key cannot be
5122 used, the signature will then not be created using this key. If the
5123 policy is not to sign at all if not all keys are valid, the client has
5124 to take care of this. All `SIGNER' commands are cumulative until a
5125 `RESET' is done. Note that a `SIGN' does not reset this list of
5126 signers which is in contrats to the `RECIPIENT' command.
5129 File: gnupg.info, Node: GPGSM VERIFY, Next: GPGSM GENKEY, Prev: GPGSM SIGN, Up: GPGSM Protocol
5131 4.8.4 Verifying a Message
5132 -------------------------
5134 To verify a mesage the command:
5138 is used. It does a verify operation on the message send to the input
5139 FD. The result is written out using status lines. If an output FD was
5140 given, the signed text will be written to that. If the signature is a
5141 detached one, the server will inquire about the signed material and the
5142 client must provide it.
5145 File: gnupg.info, Node: GPGSM GENKEY, Next: GPGSM LISTKEYS, Prev: GPGSM VERIFY, Up: GPGSM Protocol
5147 4.8.5 Generating a Key
5148 ----------------------
5150 This is used to generate a new keypair, store the secret part in the
5151 PSE and the public key in the key database. We will probably add
5152 optional commands to allow the client to select whether a hardware
5153 token is used to store the key. Configuration options to `GPGSM' can
5154 be used to restrict the use of this command.
5158 `GPGSM' checks whether this command is allowed and then does an
5159 INQUIRY to get the key parameters, the client should then send the key
5160 parameters in the native format:
5162 S: INQUIRE KEY_PARAM native
5167 Please note that the server may send Status info lines while reading
5168 the data lines from the client. After this the key generation takes
5169 place and the server eventually does send an ERR or OK response.
5170 Status lines may be issued as a progress indicator.
5173 File: gnupg.info, Node: GPGSM LISTKEYS, Next: GPGSM EXPORT, Prev: GPGSM GENKEY, Up: GPGSM Protocol
5175 4.8.6 List available keys
5176 -------------------------
5178 To list the keys in the internal database or using an external key
5179 provider, the command:
5183 is used. To allow multiple patterns (which are ORed during the
5184 search) quoting is required: Spaces are to be translated into "+" or
5185 into "%20"; in turn this requires that the usual escape quoting rules
5188 LISTSECRETKEYS PATTERN
5190 Lists only the keys where a secret key is available.
5192 The list commands commands are affected by the option
5194 OPTION list-mode=MODE
5198 Use default (which is usually the same as 1).
5201 List only the internal keys.
5204 List only the external keys.
5207 List internal and external keys.
5209 Note that options are valid for the entire session.
5212 File: gnupg.info, Node: GPGSM EXPORT, Next: GPGSM IMPORT, Prev: GPGSM LISTKEYS, Up: GPGSM Protocol
5214 4.8.7 Export certificates
5215 -------------------------
5217 To export certificate from the internal key database the command:
5219 EXPORT [--data [--armor] [--base64]] [--] PATTERN
5221 is used. To allow multiple patterns (which are ORed) quoting is
5222 required: Spaces are to be translated into "+" or into "%20"; in turn
5223 this requires that the usual escape quoting rules are done.
5225 If the `--data' option has not been given, the format of the output
5226 depends on what was set with the OUTPUT command. When using PEM
5227 encoding a few informational lines are prepended.
5229 If the `--data' has been given, a target set via OUTPUT is ignored
5230 and the data is returned inline using standard `D'-lines. This avoids
5231 the need for an extra file descriptor. In this case the options
5232 `--armor' and `--base64' may be used in the same way as with the OUTPUT
5236 File: gnupg.info, Node: GPGSM IMPORT, Next: GPGSM DELETE, Prev: GPGSM EXPORT, Up: GPGSM Protocol
5238 4.8.8 Import certificates
5239 -------------------------
5241 To import certificates into the internal key database, the command
5243 IMPORT [--re-import]
5245 is used. The data is expected on the file descriptor set with the
5246 `INPUT' command. Certain checks are performed on the certificate.
5247 Note that the code will also handle PKCS#12 files and import private
5248 keys; a helper program is used for that.
5250 With the option `--re-import' the input data is expected to a be a
5251 linefeed separated list of fingerprints. The command will re-import
5252 the corresponding certificates; that is they are made permanent by
5253 removing their ephemeral flag.
5256 File: gnupg.info, Node: GPGSM DELETE, Next: GPGSM GETINFO, Prev: GPGSM IMPORT, Up: GPGSM Protocol
5258 4.8.9 Delete certificates
5259 -------------------------
5261 To delete a certificate the command
5265 is used. To allow multiple patterns (which are ORed) quoting is
5266 required: Spaces are to be translated into "+" or into "%20"; in turn
5267 this requires that the usual escape quoting rules are done.
5269 The certificates must be specified unambiguously otherwise an error
5273 File: gnupg.info, Node: GPGSM GETINFO, Prev: GPGSM DELETE, Up: GPGSM Protocol
5275 4.8.10 Return information about the process
5276 -------------------------------------------
5278 This is a multipurpose function to return a variety of information.
5282 The value of WHAT specifies the kind of information returned:
5284 Return the version of the program.
5287 Return the process id of the process.
5290 Return success if the agent is running.
5292 `cmd_has_option CMD OPT'
5293 Return success if the command CMD implements the option OPT. The
5294 leading two dashes usually used with OPT shall not be given.
5297 File: gnupg.info, Node: Invoking SCDAEMON, Next: Specify a User ID, Prev: Invoking GPGSM, Up: Top
5299 5 Invoking the SCDAEMON
5300 ***********************
5302 The `scdaemon' is a daemon to manage smartcards. It is usually invoked
5303 by `gpg-agent' and in general not used directly.
5305 *Note Option Index::, for an index to `scdaemon''s commands and
5310 * Scdaemon Commands:: List of all commands.
5311 * Scdaemon Options:: List of all options.
5312 * Card applications:: Description of card applications.
5313 * Scdaemon Configuration:: Configuration files.
5314 * Scdaemon Examples:: Some usage examples.
5315 * Scdaemon Protocol:: The protocol the daemon uses.
5318 File: gnupg.info, Node: Scdaemon Commands, Next: Scdaemon Options, Up: Invoking SCDAEMON
5323 Commands are not distinguished from options except for the fact that
5324 only one command is allowed.
5327 Print the program version and licensing information. Not that you
5328 can abbreviate this command.
5331 Print a usage message summarizing the most useful command-line
5332 options. Not that you can abbreviate this command.
5335 Print a list of all available options and commands. Not that you
5336 can abbreviate this command.
5339 Run in server mode and wait for commands on the `stdin'. This is
5340 default mode is to create a socket and listen for commands there.
5343 Run in server mode and wait for commands on the `stdin' as well as
5344 on an additional Unix Domain socket. The server command `GETINFO'
5345 may be used to get the name of that extra socket.
5348 Run the program in the background. This option is required to
5349 prevent it from being accidentally running in the background.
5353 File: gnupg.info, Node: Scdaemon Options, Next: Card applications, Prev: Scdaemon Commands, Up: Invoking SCDAEMON
5359 Reads configuration from FILE instead of from the default per-user
5360 configuration file. The default configuration file is named
5361 `scdaemon.conf' and expected in the `.gnupg' directory directly
5362 below the home directory of the user.
5365 Set the name of the home directory to DIR. If this option is not
5366 used, the home directory defaults to `~/.gnupg'. It is only
5367 recognized when given on the command line. It also overrides any
5368 home directory stated through the environment variable `GNUPGHOME'
5369 or (on W32 systems) by means of the Registry entry
5370 HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
5375 Outputs additional information while running. You can increase
5376 the verbosity by giving several verbose commands to `gpgsm', such
5379 `--debug-level LEVEL'
5380 Select the debug level for investigating problems. LEVEL may be a
5381 numeric value or a keyword:
5384 No debugging at all. A value of less than 1 may be used
5385 instead of the keyword.
5388 Some basic debug messages. A value between 1 and 2 may be
5389 used instead of the keyword.
5392 More verbose debug messages. A value between 3 and 5 may be
5393 used instead of the keyword.
5396 Even more detailed messages. A value between 6 and 8 may be
5397 used instead of the keyword.
5400 All of the debug messages you can get. A value greater than 8
5401 may be used instead of the keyword. The creation of hash
5402 tracing files is only enabled if the keyword is used.
5404 How these messages are mapped to the actual debugging flags is not
5405 specified and may change with newer releases of this program. They
5406 are however carefully selected to best aid in debugging.
5408 Note: All debugging options are subject to change and thus
5409 should not be used by any application program. As the name
5410 says, they are only used as helpers to debug problems.
5413 This option is only useful for debugging and the behaviour may
5414 change at any time without notice. FLAGS are bit encoded and may
5415 be given in usual C-Syntax. The currently defined bits are:
5421 values of big number integers
5424 low level crypto operations
5433 show memory statistics.
5436 write hashed data to files named `dbgmd-000*'
5439 trace Assuan protocol. See also option
5440 `--debug-assuan-log-cats'.
5443 trace APDU I/O to the card. This may reveal sensitive data.
5446 trace some card reader related function calls.
5449 Same as `--debug=0xffffffff'
5452 When running in server mode, wait N seconds before entering the
5453 actual processing loop and print the pid. This gives time to
5456 `--debug-ccid-driver'
5457 Enable debug output from the included CCID driver for smartcards.
5458 Using this option twice will also enable some tracing of the T=1
5459 protocol. Note that this option may reveal sensitive data.
5461 `--debug-disable-ticker'
5462 This option disables all ticker functions like checking for card
5465 `--debug-allow-core-dump'
5466 For security reasons we won't create a core dump when the process
5467 aborts. For debugging purposes it is sometimes better to allow
5468 core dump. This options enables it and also changes the working
5469 directory to `/tmp' when running in `--server' mode.
5472 This option appends a thread ID to the PID in the log output.
5474 `--debug-assuan-log-cats CATS'
5475 Changes the active Libassuan logging categories to CATS. The
5476 value for CATS is an unsigned integer given in usual C-Syntax. A
5477 value of of 0 switches to a default category. If this option is
5478 not used the categories are taken from the environment variable
5479 `ASSUAN_DEBUG'. Note that this option has only an effect if the
5480 Assuan debug flag has also been with the option `--debug'. For a
5481 list of categories see the Libassuan manual.
5484 Don't detach the process from the console. This is mainly useful
5488 Append all logging output to FILE. This is very helpful in seeing
5489 what the agent actually does.
5491 `--pcsc-driver LIBRARY'
5492 Use LIBRARY to access the smartcard reader. The current default
5493 is `libpcsclite.so'. Instead of using this option you might also
5494 want to install a symbolic link to the default file name (e.g.
5495 from `libpcsclite.so.1').
5497 `--ctapi-driver LIBRARY'
5498 Use LIBRARY to access the smartcard reader. The current default
5499 is `libtowitoko.so'. Note that the use of this interface is
5500 deprecated; it may be removed in future releases.
5503 Disable the integrated support for CCID compliant readers. This
5504 allows to fall back to one of the other drivers even if the
5505 internal CCID driver can handle the reader. Note, that CCID
5506 support is only available if libusb was available at build time.
5508 `--reader-port NUMBER_OR_STRING'
5509 This option may be used to specify the port of the card terminal.
5510 A value of 0 refers to the first serial device; add 32768 to
5511 access USB devices. The default is 32768 (first USB device).
5512 PC/SC or CCID readers might need a string here; run the program in
5513 verbose mode to get a list of available readers. The default is
5514 then the first reader found.
5516 To get a list of available CCID readers you may use this command:
5517 echo scd getinfo reader_list | gpg-connect-agent --decode | awk '/^D/ {print $2}'
5520 If N is not 0 and no client is actively using the card, the card
5521 will be powered down after N seconds. Powering down the card
5522 avoids a potential risk of damaging a card when used with certain
5523 cheap readers. This also allows non Scdaemon aware applications to
5524 access the card. The disadvantage of using a card timeout is that
5525 accessing the card takes longer and that the user needs to enter
5526 the PIN again after the next power up.
5528 Note that with the current version of Scdaemon the card is powered
5529 down immediately at the next timer tick for any value of N other
5533 Even if a card reader features a keypad, do not try to use it.
5536 This option disables the use of admin class commands for card
5537 applications where this is supported. Currently we support it for
5538 the OpenPGP card. This commands is useful to inhibit accidental
5539 access to admin class command which could ultimately lock the card
5540 through wrong PIN numbers. Note that GnuPG versions older than
5541 2.0.11 featured an `--allow-admin' command which was required to
5542 use such admin commands. This option has no more effect today
5543 because the default is now to allow admin commands.
5545 `--disable-application NAME'
5546 This option disables the use of the card application named NAME.
5547 This is mainly useful for debugging or if a application with lower
5548 priority should be used by default.
5551 All the long options may also be given in the configuration file
5552 after stripping off the two leading dashes.
5555 File: gnupg.info, Node: Card applications, Next: Scdaemon Configuration, Prev: Scdaemon Options, Up: Invoking SCDAEMON
5557 5.3 Description of card applications
5558 ====================================
5560 `scdaemon' supports the card applications as described below.
5564 * OpenPGP Card:: The OpenPGP card application
5565 * NKS Card:: The Telesec NetKey card application
5566 * DINSIG Card:: The DINSIG card application
5567 * PKCS#15 Card:: The PKCS#15 card application
5568 * Geldkarte Card:: The Geldkarte application
5569 * Undefined Card:: The Undefined stub application
5572 File: gnupg.info, Node: OpenPGP Card, Next: NKS Card, Up: Card applications
5574 5.3.1 The OpenPGP card application "openpgp"
5575 --------------------------------------------
5577 This application is currently only used by `gpg' but may in future also
5578 be useful with `gpgsm'. Version 1 and version 2 of the card is
5581 The specifications for these cards are available at
5582 `http://g10code.com/docs/openpgp-card-1.0.pdf' and
5583 `http://g10code.com/docs/openpgp-card-2.0.pdf'.
5586 File: gnupg.info, Node: NKS Card, Next: DINSIG Card, Prev: OpenPGP Card, Up: Card applications
5588 5.3.2 The Telesec NetKey card "nks"
5589 -----------------------------------
5591 This is the main application of the Telesec cards as available in
5592 Germany. It is a superset of the German DINSIG card. The card is used
5596 File: gnupg.info, Node: DINSIG Card, Next: PKCS#15 Card, Prev: NKS Card, Up: Card applications
5598 5.3.3 The DINSIG card application "dinsig"
5599 ------------------------------------------
5601 This is an application as described in the German draft standard _DIN V
5602 66291-1_. It is intended to be used by cards supporting the German
5603 signature law and its bylaws (SigG and SigV).
5606 File: gnupg.info, Node: PKCS#15 Card, Next: Geldkarte Card, Prev: DINSIG Card, Up: Card applications
5608 5.3.4 The PKCS#15 card application "p15"
5609 ----------------------------------------
5611 This is common framework for smart card applications. It is used by
5615 File: gnupg.info, Node: Geldkarte Card, Next: Undefined Card, Prev: PKCS#15 Card, Up: Card applications
5617 5.3.5 The Geldkarte card application "geldkarte"
5618 ------------------------------------------------
5620 This is a simple application to display information of a German
5621 Geldkarte. The Geldkarte is a small amount debit card application which
5622 comes with almost all German banking cards.
5625 File: gnupg.info, Node: Undefined Card, Prev: Geldkarte Card, Up: Card applications
5627 5.3.6 The Undefined card application "undefined"
5628 ------------------------------------------------
5630 This is a stub application to allow the use of the APDU command even if
5631 no supported application is found on the card. This application is not
5632 used automatically but must be explicitly requested using the SERIALNO
5636 File: gnupg.info, Node: Scdaemon Configuration, Next: Scdaemon Examples, Prev: Card applications, Up: Invoking SCDAEMON
5638 5.4 Configuration files
5639 =======================
5641 There are a few configuration files to control certain aspects of
5642 `scdaemons''s operation. Unless noted, they are expected in the current
5643 home directory (*note option --homedir::).
5646 This is the standard configuration file read by `scdaemon' on
5647 startup. It may contain any valid long option; the leading two
5648 dashes may not be entered and the option may not be abbreviated.
5649 This default name may be changed on the command line (*note option
5653 If this file is present and executable, it will be called on veyer
5654 card reader's status changed. An example of this script is
5655 provided with the distribution
5658 This file is created by `sdaemon' to let other applications now
5659 about reader status changes. Its use is now deprecated in favor of
5664 File: gnupg.info, Node: Scdaemon Examples, Next: Scdaemon Protocol, Prev: Scdaemon Configuration, Up: Invoking SCDAEMON
5669 $ scdaemon --server -v
5672 File: gnupg.info, Node: Scdaemon Protocol, Prev: Scdaemon Examples, Up: Invoking SCDAEMON
5674 5.6 Scdaemon's Assuan Protocol
5675 ==============================
5677 The SC-Daemon should be started by the system to provide access to
5678 external tokens. Using Smartcards on a multi-user system does not make
5679 much sense expect for system services, but in this case no regular user
5680 accounts are hosted on the machine.
5682 A client connects to the SC-Daemon by connecting to the socket named
5683 `/var/run/scdaemon/socket', configuration information is read from
5686 Each connection acts as one session, SC-Daemon takes care of
5687 synchronizing access to a token between sessions.
5691 * Scdaemon SERIALNO:: Return the serial number.
5692 * Scdaemon LEARN:: Read all useful information from the card.
5693 * Scdaemon READCERT:: Return a certificate.
5694 * Scdaemon READKEY:: Return a public key.
5695 * Scdaemon PKSIGN:: Signing data with a Smartcard.
5696 * Scdaemon PKDECRYPT:: Decrypting data with a Smartcard.
5697 * Scdaemon GETATTR:: Read an attribute's value.
5698 * Scdaemon SETATTR:: Update an attribute's value.
5699 * Scdaemon WRITEKEY:: Write a key to a card.
5700 * Scdaemon GENKEY:: Generate a new key on-card.
5701 * Scdaemon RANDOM:: Return random bytes generate on-card.
5702 * Scdaemon PASSWD:: Change PINs.
5703 * Scdaemon CHECKPIN:: Perform a VERIFY operation.
5704 * Scdaemon RESTART:: Restart connection
5705 * Scdaemon APDU:: Send a verbatim APDU to the card
5708 File: gnupg.info, Node: Scdaemon SERIALNO, Next: Scdaemon LEARN, Up: Scdaemon Protocol
5710 5.6.1 Return the serial number
5711 ------------------------------
5713 This command should be used to check for the presence of a card. It is
5714 special in that it can be used to reset the card. Most other commands
5715 will return an error when a card change has been detected and the use of
5716 this function is therefore required.
5718 Background: We want to keep the client clear of handling card changes
5719 between operations; i.e. the client can assume that all operations are
5720 done on the same card unless he call this function.
5724 Return the serial number of the card using a status response like:
5726 S SERIALNO D27600000000000000000000 0
5728 The trailing 0 should be ignored for now, it is reserved for a future
5729 extension. The serial number is the hex encoded value identified by
5730 the `0x5A' tag in the GDO file (FIX=0x2F02).
5733 File: gnupg.info, Node: Scdaemon LEARN, Next: Scdaemon READCERT, Prev: Scdaemon SERIALNO, Up: Scdaemon Protocol
5735 5.6.2 Read all useful information from the card
5736 -----------------------------------------------
5740 Learn all useful information of the currently inserted card. When
5741 used without the force options, the command might do an INQUIRE like
5744 INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
5746 The client should just send an `END' if the processing should go on
5747 or a `CANCEL' to force the function to terminate with a cancel error
5748 message. The response of this command is a list of status lines
5751 S KEYPAIRINFO HEXSTRING_WITH_KEYGRIP HEXSTRING_WITH_ID
5753 If there is no certificate yet stored on the card a single "X" is
5754 returned in HEXSTRING_WITH_KEYGRIP.
5757 File: gnupg.info, Node: Scdaemon READCERT, Next: Scdaemon READKEY, Prev: Scdaemon LEARN, Up: Scdaemon Protocol
5759 5.6.3 Return a certificate
5760 --------------------------
5762 READCERT HEXIFIED_CERTID|KEYID
5764 This function is used to read a certificate identified by
5765 HEXIFIED_CERTID from the card. With OpenPGP cards the keyid
5766 `OpenPGP.3' may be used to rad the certificate of version 2 cards.
5769 File: gnupg.info, Node: Scdaemon READKEY, Next: Scdaemon PKSIGN, Prev: Scdaemon READCERT, Up: Scdaemon Protocol
5771 5.6.4 Return a public key
5772 -------------------------
5774 READKEY HEXIFIED_CERTID
5776 Return the public key for the given cert or key ID as an standard
5780 File: gnupg.info, Node: Scdaemon PKSIGN, Next: Scdaemon PKDECRYPT, Prev: Scdaemon READKEY, Up: Scdaemon Protocol
5782 5.6.5 Signing data with a Smartcard
5783 -----------------------------------
5785 To sign some data the caller should use the command
5789 to tell `scdaemon' about the data to be signed. The data must be
5790 given in hex notation. The actual signing is done using the command
5794 where KEYID is the hexified ID of the key to be used. The key id
5795 may have been retrieved using the command `LEARN'. If another hash
5796 algorithm than SHA-1 is used, that algorithm may be given like:
5798 PKSIGN --hash=ALGONAME KEYID
5800 With ALGONAME are one of `sha1', `rmd160' or `md5'.
5803 File: gnupg.info, Node: Scdaemon PKDECRYPT, Next: Scdaemon GETATTR, Prev: Scdaemon PKSIGN, Up: Scdaemon Protocol
5805 5.6.6 Decrypting data with a Smartcard
5806 --------------------------------------
5808 To decrypt some data the caller should use the command
5812 to tell `scdaemon' about the data to be decrypted. The data must be
5813 given in hex notation. The actual decryption is then done using the
5818 where KEYID is the hexified ID of the key to be used.
5821 File: gnupg.info, Node: Scdaemon GETATTR, Next: Scdaemon SETATTR, Prev: Scdaemon PKDECRYPT, Up: Scdaemon Protocol
5823 5.6.7 Read an attribute's value.
5824 --------------------------------
5829 File: gnupg.info, Node: Scdaemon SETATTR, Next: Scdaemon WRITEKEY, Prev: Scdaemon GETATTR, Up: Scdaemon Protocol
5831 5.6.8 Update an attribute's value.
5832 ----------------------------------
5837 File: gnupg.info, Node: Scdaemon WRITEKEY, Next: Scdaemon GENKEY, Prev: Scdaemon SETATTR, Up: Scdaemon Protocol
5839 5.6.9 Write a key to a card.
5840 ----------------------------
5842 WRITEKEY [--force] KEYID
5844 This command is used to store a secret key on a smartcard. The
5845 allowed keyids depend on the currently selected smartcard application.
5846 The actual keydata is requested using the inquiry `KEYDATA' and need to
5847 be provided without any protection. With `--force' set an existing key
5848 under this KEYID will get overwritten. The key data is expected to be
5849 the usual canonical encoded S-expression.
5851 A PIN will be requested in most cases. This however depends on the
5852 actual card application.
5855 File: gnupg.info, Node: Scdaemon GENKEY, Next: Scdaemon RANDOM, Prev: Scdaemon WRITEKEY, Up: Scdaemon Protocol
5857 5.6.10 Generate a new key on-card.
5858 ----------------------------------
5863 File: gnupg.info, Node: Scdaemon RANDOM, Next: Scdaemon PASSWD, Prev: Scdaemon GENKEY, Up: Scdaemon Protocol
5865 5.6.11 Return random bytes generate on-card.
5866 --------------------------------------------
5871 File: gnupg.info, Node: Scdaemon PASSWD, Next: Scdaemon CHECKPIN, Prev: Scdaemon RANDOM, Up: Scdaemon Protocol
5876 PASSWD [--reset] [--nullpin] CHVNO
5878 Change the PIN or reset the retry counter of the card holder
5879 verification vector number CHVNO. The option `--nullpin' is used to
5880 initialize the PIN of TCOS cards (6 byte NullPIN only).
5883 File: gnupg.info, Node: Scdaemon CHECKPIN, Next: Scdaemon RESTART, Prev: Scdaemon PASSWD, Up: Scdaemon Protocol
5885 5.6.13 Perform a VERIFY operation.
5886 ----------------------------------
5890 Perform a VERIFY operation without doing anything else. This may be
5891 used to initialize a the PIN cache earlier to long lasting operations.
5892 Its use is highly application dependent:
5895 Perform a simple verify operation for CHV1 and CHV2, so that
5896 further operations won't ask for CHV2 and it is possible to do a
5897 cheap check on the PIN: If there is something wrong with the PIN
5898 entry system, only the regular CHV will get blocked and not the
5899 dangerous CHV3. IDSTR is the usual card's serial number in hex
5900 notation; an optional fingerprint part will get ignored.
5902 There is however a special mode if IDSTR is suffixed with the
5903 literal string `[CHV3]': In this case the Admin PIN is checked if
5904 and only if the retry counter is still at 3.
5908 File: gnupg.info, Node: Scdaemon RESTART, Next: Scdaemon APDU, Prev: Scdaemon CHECKPIN, Up: Scdaemon Protocol
5910 5.6.14 Perform a RESTART operation.
5911 -----------------------------------
5915 Restart the current connection; this is a kind of warm reset. It
5916 deletes the context used by this connection but does not actually reset
5919 This is used by gpg-agent to reuse a primary pipe connection and may
5920 be used by clients to backup from a conflict in the serial command;
5921 i.e. to select another application.
5924 File: gnupg.info, Node: Scdaemon APDU, Prev: Scdaemon RESTART, Up: Scdaemon Protocol
5926 5.6.15 Send a verbatim APDU to the card.
5927 ----------------------------------------
5929 APDU [--atr] [--more] [--exlen[=N]] [HEXSTRING]
5931 Send an APDU to the current reader. This command bypasses the high
5932 level functions and sends the data directly to the card. HEXSTRING is
5933 expected to be a proper APDU. If HEXSTRING is not given no commands
5934 are send to the card; However the command will implicitly check whether
5935 the card is ready for use.
5937 Using the option `--atr' returns the ATR of the card as a status
5938 message before any data like this:
5939 S CARD-ATR 3BFA1300FF813180450031C173C00100009000B1
5941 Using the option `--more' handles the card status word MORE_DATA
5942 (61xx) and concatenate all responses to one block.
5944 Using the option `--exlen' the returned APDU may use extended length
5945 up to N bytes. If N is not given a default value is used (currently
5949 File: gnupg.info, Node: Specify a User ID, Next: Helper Tools, Prev: Invoking SCDAEMON, Up: Top
5951 6 How to Specify a User Id
5952 **************************
5954 There are different ways to specify a user ID to GnuPG. Some of them
5955 are only valid for `gpg' others are only good for `gpgsm'. Here is the
5956 entire list of ways to specify a key:
5958 * By key Id. This format is deduced from the length of the string
5959 and its content or `0x' prefix. The key Id of an X.509 certificate
5960 are the low 64 bits of its SHA-1 fingerprint. The use of key Ids
5961 is just a shortcut, for all automated processing the fingerprint
5964 When using `gpg' an exclamation mark (!) may be appended to force
5965 using the specified primary or secondary key and not to try and
5966 calculate which primary or secondary key to use.
5968 The last four lines of the example give the key ID in their long
5969 form as internally used by the OpenPGP protocol. You can see the
5970 long key ID using the option `--with-colons'.
5982 * By fingerprint. This format is deduced from the length of the
5983 string and its content or the `0x' prefix. Note, that only the 20
5984 byte version fingerprint is available with `gpgsm' (i.e. the SHA-1
5985 hash of the certificate).
5987 When using `gpg' an exclamation mark (!) may be appended to force
5988 using the specified primary or secondary key and not to try and
5989 calculate which primary or secondary key to use.
5991 The best way to specify a key Id is by using the fingerprint. This
5992 avoids any ambiguities in case that there are duplicated key IDs.
5994 1234343434343434C434343434343434
5995 123434343434343C3434343434343734349A3434
5996 0E12343434343434343434EAB3484343434343434
5997 0xE12343434343434343434EAB3484343434343434
5999 (`gpgsm' also accepts colons between each pair of hexadecimal
6000 digits because this is the de-facto standard on how to present
6001 X.509 fingerprints.)
6003 * By exact match on OpenPGP user ID. This is denoted by a leading
6004 equal sign. It does not make sense for X.509 certificates.
6006 =Heinrich Heine <heinrichh@uni-duesseldorf.de>
6008 * By exact match on an email address. This is indicated by
6009 enclosing the email address in the usual way with left and right
6012 <heinrichh@uni-duesseldorf.de>
6014 * By word match. All words must match exactly (not case sensitive)
6015 but can appear in any order in the user ID or a subjects name.
6016 Words are any sequences of letters, digits, the underscore and all
6017 characters with bit 7 set.
6019 +Heinrich Heine duesseldorf
6021 * By exact match on the subject's DN. This is indicated by a
6022 leading slash, directly followed by the RFC-2253 encoded DN of the
6023 subject. Note that you can't use the string printed by "gpgsm
6024 -list-keys" because that one as been reordered and modified for
6025 better readability; use -with-colons to print the raw (but standard
6026 escaped) RFC-2253 string
6028 /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
6030 * By exact match on the issuer's DN. This is indicated by a leading
6031 hash mark, directly followed by a slash and then directly followed
6032 by the rfc2253 encoded DN of the issuer. This should return the
6033 Root cert of the issuer. See note above.
6035 #/CN=Root Cert,O=Poets,L=Paris,C=FR
6037 * By exact match on serial number and issuer's DN. This is
6038 indicated by a hash mark, followed by the hexadecimal
6039 representation of the serial number, then followed by a slash and
6040 the RFC-2253 encoded DN of the issuer. See note above.
6042 #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
6044 * By keygrip This is indicated by an ampersand followed by the 40
6045 hex digits of a keygrip. `gpgsm' prints the keygrip when using
6046 the command `--dump-cert'. It does not yet work for OpenPGP keys.
6048 &D75F22C3F86E355877348498CDC92BD21010A480
6050 * By substring match. This is the default mode but applications may
6051 want to explicitly indicate this by putting the asterisk in front.
6052 Match is not case sensitive.
6058 Please note that we have reused the hash mark identifier which was
6059 used in old GnuPG versions to indicate the so called local-id. It is
6060 not anymore used and there should be no conflict when used with X.509
6063 Using the RFC-2253 format of DNs has the drawback that it is not
6064 possible to map them back to the original encoding, however we don't
6065 have to do this because our key database stores this encoding as meta
6069 File: gnupg.info, Node: Helper Tools, Next: Howtos, Prev: Specify a User ID, Up: Top
6074 GnuPG comes with a couple of smaller tools:
6078 * watchgnupg:: Read logs from a socket.
6079 * gpgv:: Verify OpenPGP signatures.
6080 * addgnupghome:: Create .gnupg home directories.
6081 * gpgconf:: Modify .gnupg home directories.
6082 * applygnupgdefaults:: Run gpgconf for all users.
6083 * gpgsm-gencert.sh:: Generate an X.509 certificate request.
6084 * gpg-preset-passphrase:: Put a passphrase into the cache.
6085 * gpg-connect-agent:: Communicate with a running agent.
6086 * gpgparsemail:: Parse a mail message into an annotated format
6087 * symcryptrun:: Call a simple symmetric encryption tool.
6088 * gpg-zip:: Encrypt or sign files into an archive.
6091 File: gnupg.info, Node: watchgnupg, Next: gpgv, Up: Helper Tools
6093 7.1 Read logs from a socket
6094 ===========================
6096 Most of the main utilities are able to write their log files to a Unix
6097 Domain socket if configured that way. `watchgnupg' is a simple
6098 listener for such a socket. It ameliorates the output with a time stamp
6099 and makes sure that long lines are not interspersed with log output from
6100 other utilities. This tool is not available for Windows.
6102 `watchgnupg' is commonly invoked as
6104 watchgnupg --force ~/.gnupg/S.log
6106 This starts it on the current terminal for listening on the socket
6109 `watchgnupg' understands these options:
6112 Delete an already existing socket file.
6115 Instead of reading from a local socket, listen for connects on TCP
6119 Enable extra informational output.
6122 Print version of the program and exit.
6125 Display a brief help page and exit.
6132 $ watchgnupg --force /home/foo/.gnupg/S.log
6134 This waits for connections on the local socket
6135 `/home/foo/.gnupg/S.log' and shows all log entries. To make this work
6136 the option `log-file' needs to be used with all modules which logs are
6137 to be shown. The value for that option must be given with a special
6138 prefix (e.g. in the conf file):
6140 log-file socket:///home/foo/.gnupg/S.log
6142 For debugging purposes it is also possible to do remote logging.
6143 Take care if you use this feature because the information is send in the
6144 clear over the network. Use this syntax in the conf files:
6146 log-file tcp://192.168.1.1:4711
6148 You may use any port and not just 4711 as shown above; only IP
6149 addresses are supported (v4 and v6) and no host names. You need to
6150 start `watchgnupg' with the `tcp' option. Note that under Windows the
6151 registry entry HKCU\SOFTWARE\GNU\GNUPG:DEFAULTLOGFILE can be used to
6152 change the default log output from `stderr' to whatever is given by
6153 that entry. However the only useful entry is a TCP name for remote
6157 File: gnupg.info, Node: gpgv, Next: addgnupghome, Prev: watchgnupg, Up: Helper Tools
6159 7.2 Verify OpenPGP signatures
6160 =============================
6162 `gpgv2' is an OpenPGP signature verification tool.
6164 This program is actually a stripped-down version of `gpg' which is
6165 only able to check signatures. It is somewhat smaller than the
6166 fully-blown `gpg' and uses a different (and simpler) way to check that
6167 the public keys used to make the signature are valid. There are no
6168 configuration files and only a few options are implemented.
6170 `gpgv2' assumes that all keys in the keyring are trustworthy. By
6171 default it uses a keyring named `trustedkeys.gpg' which is assumed to
6172 be in the home directory as defined by GnuPG or set by an option or an
6173 environment variable. An option may be used to specify another keyring
6174 or even multiple keyrings.
6178 `gpgv2' recognizes these options:
6182 Gives more information during processing. If used twice, the input
6183 data is listed in detail.
6187 Try to be as quiet as possible.
6190 Add FILE to the list of keyrings. If FILE begins with a tilde and
6191 a slash, these are replaced by the HOME directory. If the filename
6192 does not contain a slash, it is assumed to be in the
6193 home-directory ("~/.gnupg" if -homedir is not used).
6196 Write special status strings to the file descriptor N. See the
6197 file DETAILS in the documentation for a listing of them.
6200 Write log output to file descriptor `n' and not to stderr.
6202 `--ignore-time-conflict'
6203 GnuPG normally checks that the timestamps associated with keys and
6204 signatures have plausible values. However, sometimes a signature
6205 seems to be older than the key due to clock problems. This option
6206 turns these checks into warnings.
6209 Set the name of the home directory to DIR. If this option is not
6210 used, the home directory defaults to `~/.gnupg'. It is only
6211 recognized when given on the command line. It also overrides any
6212 home directory stated through the environment variable `GNUPGHOME'
6213 or (on W32 systems) by means of the Registry entry
6214 HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
6217 The program returns 0 if everything is fine, 1 if at least one
6218 signature was bad, and other error codes for fatal errors.
6224 gpgv2 `sigfile' [`datafile']
6225 Verify the signature of the file. The second form is used for
6226 detached signatures, where `sigfile' is the detached signature
6227 (either ASCII-armored or binary) and `datafile' contains the
6228 signed data; if `datafile' is "-" the signed data is expected on
6229 `stdin'; if `datafile' is not given the name of the file holding
6230 the signed data is constructed by cutting off the extension
6231 (".asc", ".sig" or ".sign") from `sigfile'.
6238 Used to locate the default home directory.
6241 If set directory used instead of "~/.gnupg".
6247 ~/.gnupg/trustedkeys.gpg
6248 The default keyring with the allowed keys.
6254 File: gnupg.info, Node: addgnupghome, Next: gpgconf, Prev: gpgv, Up: Helper Tools
6256 7.3 Create .gnupg home directories.
6257 ===================================
6259 If GnuPG is installed on a system with existing user accounts, it is
6260 sometimes required to populate the GnuPG home directory with existing
6261 files. Especially a `trustlist.txt' and a keybox with some initial
6262 certificates are often desired. This scripts help to do this by
6263 copying all files from `/etc/skel/.gnupg' to the home directories of
6264 the accounts given on the command line. It takes care not to overwrite
6265 existing GnuPG home directories.
6267 `addgnupghome' is invoked by root as:
6269 addgnupghome account1 account2 ... accountn
6272 File: gnupg.info, Node: gpgconf, Next: applygnupgdefaults, Prev: addgnupghome, Up: Helper Tools
6274 7.4 Modify .gnupg home directories.
6275 ===================================
6277 The `gpgconf' is a utility to automatically and reasonable safely query
6278 and modify configuration files in the `.gnupg' home directory. It is
6279 designed not to be invoked manually by the user, but automatically by
6280 graphical user interfaces (GUI).(1)
6282 `gpgconf' provides access to the configuration of one or more
6283 components of the GnuPG system. These components correspond more or
6284 less to the programs that exist in the GnuPG framework, like GnuPG,
6285 GPGSM, DirMngr, etc. But this is not a strict one-to-one relationship.
6286 Not all configuration options are available through `gpgconf'.
6287 `gpgconf' provides a generic and abstract method to access the most
6288 important configuration options that can feasibly be controlled via
6291 `gpgconf' can be used to gather and change the options available in
6292 each component, and can also provide their default values. `gpgconf'
6293 will give detailed type information that can be used to restrict the
6294 user's input without making an attempt to commit the changes.
6296 `gpgconf' provides the backend of a configuration editor. The
6297 configuration editor would usually be a graphical user interface
6298 program, that allows to display the current options, their default
6299 values, and allows the user to make changes to the options. These
6300 changes can then be made active with `gpgconf' again. Such a program
6301 that uses `gpgconf' in this way will be called GUI throughout this
6306 * Invoking gpgconf:: List of all commands and options.
6307 * Format conventions:: Formatting conventions relevant for all commands.
6308 * Listing components:: List all gpgconf components.
6309 * Checking programs:: Check all programs know to gpgconf.
6310 * Listing options:: List all options of a component.
6311 * Changing options:: Changing options of a component.
6312 * Listing global options:: List all global options.
6313 * Files used by gpgconf:: What files are used by gpgconf.
6315 ---------- Footnotes ----------
6317 (1) Please note that currently no locking is done, so concurrent
6318 access should be avoided. There are some precautions to avoid
6319 corruption with concurrent usage, but results may be inconsistent and
6320 some changes may get lost. The stateless design makes it difficult to
6321 provide more guarantees.
6324 File: gnupg.info, Node: Invoking gpgconf, Next: Format conventions, Up: gpgconf
6326 7.4.1 Invoking gpgconf
6327 ----------------------
6329 One of the following commands must be given:
6332 List all components. This is the default command used if none is
6336 List all available backend programs and test whether they are
6339 `--list-options COMPONENT'
6340 List all options of the component COMPONENT.
6342 `--change-options COMPONENT'
6343 Change the options of the component COMPONENT.
6345 `--check-options COMPONENT'
6346 Check the options for the component COMPONENT.
6349 Update all configuration files with values taken from the global
6350 configuration file (usually `/etc/gnupg/gpgconf.conf').
6353 Lists the directories used by `gpgconf'. One directory is listed
6354 per line, and each line consists of a colon-separated list where
6355 the first field names the directory type (for example `sysconfdir')
6356 and the second field contains the percent-escaped directory.
6357 Although they are not directories, the socket file names used by
6358 `gpg-agent' and `dirmngr' are printed as well. Note that the
6359 socket file names and the `homedir' lines are the default names
6360 and they may be overridden by command line switches.
6362 `--list-config [FILENAME]'
6363 List the global configuration file in a colon separated format. If
6364 FILENAME is given, check that file instead.
6366 `--check-config [FILENAME]'
6367 Run a syntax check on the global configuration file. If FILENAME
6368 is given, check that file instead.
6370 `--reload [COMPONENT]'
6371 Reload all or the given component. This is basically the same as
6372 sending a SIGHUP to the component. Components which don't support
6373 reloading are ignored.
6375 `--kill [COMPONENT]'
6376 Kill the given component. Components which support killing are
6377 gpg-agent and scdaemon. Components which don't support reloading
6378 are ignored. Note that as of now reload and kill have the same
6379 effect for scdaemon.
6382 The following options may be used:
6386 Outputs additional information while running. Specifically, this
6387 extends numerical field values by human-readable descriptions.
6391 Do not actually change anything. This is currently only
6392 implemented for `--change-options' and can be used for testing
6397 Only used together with `--change-options'. If one of the
6398 modified options can be changed in a running daemon process, signal
6399 the running daemon to ask it to reparse its configuration file
6402 This means that the changes will take effect at run-time, as far as
6403 this is possible. Otherwise, they will take effect at the next
6404 start of the respective backend programs.
6408 File: gnupg.info, Node: Format conventions, Next: Listing components, Prev: Invoking gpgconf, Up: gpgconf
6410 7.4.2 Format conventions
6411 ------------------------
6413 Some lines in the output of `gpgconf' contain a list of colon-separated
6414 fields. The following conventions apply:
6416 * The GUI program is required to strip off trailing newline and/or
6417 carriage return characters from the output.
6419 * `gpgconf' will never leave out fields. If a certain version
6420 provides a certain field, this field will always be present in all
6421 `gpgconf' versions from that time on.
6423 * Future versions of `gpgconf' might append fields to the list. New
6424 fields will always be separated from the previously last field by
6425 a colon separator. The GUI should be prepared to parse the last
6426 field it knows about up until a colon or end of line.
6428 * Not all fields are defined under all conditions. You are required
6429 to ignore the content of undefined fields.
6431 There are several standard types for the content of a field:
6434 Some fields contain strings that are not escaped in any way. Such
6435 fields are described to be used _verbatim_. These fields will
6436 never contain a colon character (for obvious reasons). No
6437 de-escaping or other formatting is required to use the field
6438 content. This is for easy parsing of the output, when it is known
6439 that the content can never contain any special characters.
6442 Some fields contain strings that are described to be
6443 _percent-escaped_. Such strings need to be de-escaped before
6444 their content can be presented to the user. A percent-escaped
6445 string is de-escaped by replacing all occurrences of `%XY' by the
6446 byte that has the hexadecimal value `XY'. `X' and `Y' are from
6450 Some fields contain strings that are described to be _localised_.
6451 Such strings are translated to the active language and formatted in
6452 the active character set.
6455 Some fields contain an _unsigned number_. This number will always
6456 fit into a 32-bit unsigned integer variable. The number may be
6457 followed by a space, followed by a human readable description of
6458 that value (if the verbose option is used). You should ignore
6459 everything in the field that follows the number.
6462 Some fields contain a _signed number_. This number will always
6463 fit into a 32-bit signed integer variable. The number may be
6464 followed by a space, followed by a human readable description of
6465 that value (if the verbose option is used). You should ignore
6466 everything in the field that follows the number.
6469 Some fields contain a _boolean value_. This is a number with
6470 either the value 0 or 1. The number may be followed by a space,
6471 followed by a human readable description of that value (if the
6472 verbose option is used). You should ignore everything in the
6473 field that follows the number; checking just the first character
6474 is sufficient in this case.
6477 Some fields contain an _option_ argument. The format of an option
6478 argument depends on the type of the option and on some flags:
6481 The simplest case is that the option does not take an
6482 argument at all (TYPE `0'). Then the option argument is an
6483 unsigned number that specifies how often the option occurs.
6484 If the `list' flag is not set, then the only valid number is
6485 `1'. Options that do not take an argument never have the
6486 `default' or `optional arg' flag set.
6489 If the option takes a number argument (ALT-TYPE is `2' or
6490 `3'), and it can only occur once (`list' flag is not set),
6491 then the option argument is either empty (only allowed if the
6492 argument is optional), or it is a number. A number is a
6493 string that begins with an optional minus character, followed
6494 by one or more digits. The number must fit into an integer
6495 variable (unsigned or signed, depending on ALT-TYPE).
6498 If the option takes a number argument and it can occur more
6499 than once, then the option argument is either empty, or it is
6500 a comma-separated list of numbers as described above.
6503 If the option takes a string argument (ALT-TYPE is 1), and it
6504 can only occur once (`list' flag is not set) then the option
6505 argument is either empty (only allowed if the argument is
6506 optional), or it starts with a double quote character (`"')
6507 followed by a percent-escaped string that is the argument
6508 value. Note that there is only a leading double quote
6509 character, no trailing one. The double quote character is
6510 only needed to be able to differentiate between no value and
6511 the empty string as value.
6514 If the option takes a number argument and it can occur more
6515 than once, then the option argument is either empty, or it is
6516 a comma-separated list of string arguments as described above.
6518 The active language and character set are currently determined from
6519 the locale environment of the `gpgconf' program.
6522 File: gnupg.info, Node: Listing components, Next: Checking programs, Prev: Format conventions, Up: gpgconf
6524 7.4.3 Listing components
6525 ------------------------
6527 The command `--list-components' will list all components that can be
6528 configured with `gpgconf'. Usually, one component will correspond to
6529 one GnuPG-related program and contain the options of that programs
6530 configuration file that can be modified using `gpgconf'. However, this
6531 is not necessarily the case. A component might also be a group of
6532 selected options from several programs, or contain entirely virtual
6533 options that have a special effect rather than changing exactly one
6534 option in one configuration file.
6536 A component is a set of configuration options that semantically
6537 belong together. Furthermore, several changes to a component can be
6538 made in an atomic way with a single operation. The GUI could for
6539 example provide a menu with one entry for each component, or a window
6540 with one tabulator sheet per component.
6542 The command argument `--list-components' lists all available
6543 components, one per line. The format of each line is:
6545 `NAME:DESCRIPTION:PGMNAME:'
6548 This field contains a name tag of the component. The name tag is
6549 used to specify the component in all communication with `gpgconf'.
6550 The name tag is to be used _verbatim_. It is thus not in any
6554 The _string_ in this field contains a human-readable description
6555 of the component. It can be displayed to the user of the GUI for
6556 informational purposes. It is _percent-escaped_ and _localized_.
6559 The _string_ in this field contains the absolute name of the
6560 program's file. It can be used to unambiguously invoke that
6561 program. It is _percent-escaped_.
6564 $ gpgconf --list-components
6565 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
6566 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
6567 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
6568 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
6569 dirmngr:Directory Manager:/usr/local/bin/dirmngr:
6572 File: gnupg.info, Node: Checking programs, Next: Listing options, Prev: Listing components, Up: gpgconf
6574 7.4.4 Checking programs
6575 -----------------------
6577 The command `--check-programs' is similar to `--list-components' but
6578 works on backend programs and not on components. It runs each program
6579 to test whether it is installed and runnable. This also includes a
6580 syntax check of all config file options of the program.
6582 The command argument `--check-programs' lists all available
6583 programs, one per line. The format of each line is:
6585 `NAME:DESCRIPTION:PGMNAME:AVAIL:OKAY:CFGFILE:LINE:ERROR:'
6588 This field contains a name tag of the program which is identical
6589 to the name of the component. The name tag is to be used
6590 _verbatim_. It is thus not in any escaped format. This field may
6591 be empty to indicate a continuation of error descriptions for the
6592 last name. The description and pgmname fields are then also empty.
6595 The _string_ in this field contains a human-readable description
6596 of the component. It can be displayed to the user of the GUI for
6597 informational purposes. It is _percent-escaped_ and _localized_.
6600 The _string_ in this field contains the absolute name of the
6601 program's file. It can be used to unambiguously invoke that
6602 program. It is _percent-escaped_.
6605 The _boolean value_ in this field indicates whether the program is
6606 installed and runnable.
6609 The _boolean value_ in this field indicates whether the program's
6610 config file is syntactically okay.
6613 If an error occurred in the configuration file (as indicated by a
6614 false value in the field `okay'), this field has the name of the
6615 failing configuration file. It is _percent-escaped_.
6618 If an error occurred in the configuration file, this field has the
6619 line number of the failing statement in the configuration file.
6620 It is an _unsigned number_.
6623 If an error occurred in the configuration file, this field has the
6624 error text of the failing statement in the configuration file. It
6625 is _percent-escaped_ and _localized_.
6628 In the following example the `dirmngr' is not runnable and the
6629 configuration file of `scdaemon' is not okay.
6631 $ gpgconf --check-programs
6632 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
6633 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
6634 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
6635 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
6636 dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
6638 The command `--check-options COMPONENT' will verify the configuration
6639 file in the same manner as `--check-programs', but only for the
6640 component COMPONENT.
6643 File: gnupg.info, Node: Listing options, Next: Changing options, Prev: Checking programs, Up: gpgconf
6645 7.4.5 Listing options
6646 ---------------------
6648 Every component contains one or more options. Options may be gathered
6649 into option groups to allow the GUI to give visual hints to the user
6650 about which options are related.
6652 The command argument `--list-options COMPONENT' lists all options
6653 (and the groups they belong to) in the component COMPONENT, one per
6654 line. COMPONENT must be the string in the field NAME in the output of
6655 the `--list-components' command.
6657 There is one line for each option and each group. First come all
6658 options that are not in any group. Then comes a line describing a
6659 group. Then come all options that belong into each group. Then comes
6660 the next group and so on. There does not need to be any group (and in
6661 this case the output will stop after the last non-grouped option).
6663 The format of each line is:
6665 `NAME:FLAGS:LEVEL:DESCRIPTION:TYPE:ALT-TYPE:ARGNAME:DEFAULT:ARGDEF:VALUE'
6668 This field contains a name tag for the group or option. The name
6669 tag is used to specify the group or option in all communication
6670 with `gpgconf'. The name tag is to be used _verbatim_. It is
6671 thus not in any escaped format.
6674 The flags field contains an _unsigned number_. Its value is the
6675 OR-wise combination of the following flag values:
6678 If this flag is set, this is a line describing a group and
6681 The following flag values are only defined for options (that is, if
6682 the `group' flag is not used).
6685 If this flag is set, the argument is optional. This is never
6686 set for TYPE `0' (none) options.
6689 If this flag is set, the option can be given multiple times.
6692 If this flag is set, the option can be changed at runtime.
6695 If this flag is set, a default value is available.
6698 If this flag is set, a (runtime) default is available. This
6699 and the `default' flag are mutually exclusive.
6702 If this flag is set, and the `optional arg' flag is set, then
6703 the option has a special meaning if no argument is given.
6706 If this flag is set, gpgconf ignores requests to change the
6707 value. GUI frontends should grey out this option. Note,
6708 that manual changes of the configuration files are still
6712 This field is defined for options and for groups. It contains an
6713 _unsigned number_ that specifies the expert level under which this
6714 group or option should be displayed. The following expert levels
6715 are defined for options (they have analogous meaning for groups):
6718 This option should always be offered to the user.
6721 This option may be offered to advanced users.
6724 This option should only be offered to expert users.
6727 This option should normally never be displayed, not even to
6731 This option is for internal use only. Ignore it.
6733 The level of a group will always be the lowest level of all
6734 options it contains.
6737 This field is defined for options and groups. The _string_ in
6738 this field contains a human-readable description of the option or
6739 group. It can be displayed to the user of the GUI for
6740 informational purposes. It is _percent-escaped_ and _localized_.
6743 This field is only defined for options. It contains an _unsigned
6744 number_ that specifies the type of the option's argument, if any.
6745 The following types are defined:
6750 No argument allowed.
6753 An _unformatted string_.
6759 An _unsigned number_.
6764 A _string_ that describes the pathname of a file. The file
6765 does not necessarily need to exist.
6768 A _string_ that describes an LDAP server in the format:
6770 `HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN'
6772 `key fingerprint (34)'
6773 A _string_ with a 40 digit fingerprint specifying a
6777 A _string_ that describes a certificate by user ID, key ID or
6781 A _string_ that describes a certificate with a key by user ID,
6782 key ID or fingerprint.
6785 A _string_ that describes an alias list, like the one used
6786 with gpg's group option. The list consists of a key, an
6787 equal sign and space separated values.
6789 More types will be added in the future. Please see the ALT-TYPE
6790 field for information on how to cope with unknown types.
6793 This field is identical to TYPE, except that only the types `0' to
6794 `31' are allowed. The GUI is expected to present the user the
6795 option in the format specified by TYPE. But if the argument type
6796 TYPE is not supported by the GUI, it can still display the option
6797 in the more generic basic type ALT-TYPE. The GUI must support all
6798 the defined basic types to be able to display all options. More
6799 basic types may be added in future versions. If the GUI
6800 encounters a basic type it doesn't support, it should report an
6801 error and abort the operation.
6804 This field is only defined for options with an argument type TYPE
6805 that is not `0'. In this case it may contain a _percent-escaped_
6806 and _localised string_ that gives a short name for the argument.
6807 The field may also be empty, though, in which case a short name is
6811 This field is defined only for options for which the `default' or
6812 `default desc' flag is set. If the `default' flag is set, its
6813 format is that of an _option argument_ (*Note Format
6814 conventions::, for details). If the default value is empty, then
6815 no default is known. Otherwise, the value specifies the default
6816 value for this option. If the `default desc' flag is set, the
6817 field is either empty or contains a description of the effect if
6818 the option is not given.
6821 This field is defined only for options for which the `optional
6822 arg' flag is set. If the `no arg desc' flag is not set, its
6823 format is that of an _option argument_ (*Note Format
6824 conventions::, for details). If the default value is empty, then
6825 no default is known. Otherwise, the value specifies the default
6826 argument for this option. If the `no arg desc' flag is set, the
6827 field is either empty or contains a description of the effect of
6828 this option if no argument is given.
6831 This field is defined only for options. Its format is that of an
6832 _option argument_. If it is empty, then the option is not
6833 explicitly set in the current configuration, and the default
6834 applies (if any). Otherwise, it contains the current value of the
6835 option. Note that this field is also meaningful if the option
6836 itself does not take a real argument (in this case, it contains
6837 the number of times the option appears).
6840 File: gnupg.info, Node: Changing options, Next: Listing global options, Prev: Listing options, Up: gpgconf
6842 7.4.6 Changing options
6843 ----------------------
6845 The command `--change-options COMPONENT' will attempt to change the
6846 options of the component COMPONENT to the specified values. COMPONENT
6847 must be the string in the field NAME in the output of the
6848 `--list-components' command. You have to provide the options that
6849 shall be changed in the following format on standard input:
6851 `NAME:FLAGS:NEW-VALUE'
6854 This is the name of the option to change. NAME must be the string
6855 in the field NAME in the output of the `--list-options' command.
6858 The flags field contains an _unsigned number_. Its value is the
6859 OR-wise combination of the following flag values:
6862 If this flag is set, the option is deleted and the default
6863 value is used instead (if applicable).
6866 The new value for the option. This field is only defined if the
6867 `default' flag is not set. The format is that of an _option
6868 argument_. If it is empty (or the field is omitted), the default
6869 argument is used (only allowed if the argument is optional for this
6870 option). Otherwise, the option will be set to the specified value.
6872 The output of the command is the same as that of `--check-options' for
6873 the modified configuration file.
6877 To set the force option, which is of basic type `none (0)':
6879 $ echo 'force:0:1' | gpgconf --change-options dirmngr
6881 To delete the force option:
6883 $ echo 'force:16:' | gpgconf --change-options dirmngr
6885 The `--runtime' option can influence when the changes take effect.
6888 File: gnupg.info, Node: Listing global options, Next: Files used by gpgconf, Prev: Changing options, Up: gpgconf
6890 7.4.7 Listing global options
6891 ----------------------------
6893 Sometimes it is useful for applications to look at the global options
6894 file `gpgconf.conf'. The colon separated listing format is record
6895 oriented and uses the first field to identify the record type:
6898 This describes a key record to start the definition of a new
6899 ruleset for a user/group. The format of a key record is:
6904 This is the user field of the key. It is percent escaped.
6905 See the definition of the gpgconf.conf format for details.
6908 This is the group field of the key. It is percent escaped.
6911 This describes a rule record. All rule records up to the next key
6912 record make up a rule set for that key. The format of a rule
6915 `r:::COMPONENT:OPTION:FLAGS:VALUE:'
6918 This is the component part of a rule. It is a plain string.
6921 This is the option part of a rule. It is a plain string.
6924 This is the flags part of a rule. There may be only one flag
6925 per rule but by using the same component and option, several
6926 flags may be assigned to an option. It is a plain string.
6929 This is the optional value for the option. It is a percent
6930 escaped string with a single quotation mark to indicate a
6931 string. The quotation mark is only required to distinguish
6932 between no value specified and an empty string.
6935 Unknown record types should be ignored. Note that there is
6936 intentionally no feature to change the global option file through
6940 File: gnupg.info, Node: Files used by gpgconf, Prev: Listing global options, Up: gpgconf
6942 7.4.8 Files used by gpgconf
6943 ---------------------------
6945 `/etc/gnupg/gpgconf.conf'
6946 If this file exists, it is processed as a global configuration
6947 file. A commented example can be found in the `examples'
6948 directory of the distribution.
6951 File: gnupg.info, Node: applygnupgdefaults, Next: gpgsm-gencert.sh, Prev: gpgconf, Up: Helper Tools
6953 7.5 Run gpgconf for all users.
6954 ==============================
6956 This script is a wrapper around `gpgconf' to run it with the command
6957 `--apply-defaults' for all real users with an existing GnuPG home
6958 directory. Admins might want to use this script to update he GnuPG
6959 configuration files for all users after `/etc/gnupg/gpgconf.conf' has
6960 been changed. This allows to enforce certain policies for all users.
6961 Note, that this is not a bulletproof of forcing a user to use certain
6962 options. A user may always directly edit the configuration files and
6965 `applygnupgdefaults' is invoked by root as:
6970 File: gnupg.info, Node: gpgsm-gencert.sh, Next: gpg-preset-passphrase, Prev: applygnupgdefaults, Up: Helper Tools
6972 7.6 Generate an X.509 certificate request
6973 =========================================
6975 This is a simple tool to interactively generate a certificate request
6976 which will be printed to stdout.
6978 `gpgsm-gencert.sh' is invoked as:
6983 File: gnupg.info, Node: gpg-preset-passphrase, Next: gpg-connect-agent, Prev: gpgsm-gencert.sh, Up: Helper Tools
6985 7.7 Put a passphrase into the cache.
6986 ====================================
6988 The `gpg-preset-passphrase' is a utility to seed the internal cache of
6989 a running `gpg-agent' with passphrases. It is mainly useful for
6990 unattended machines, where the usual `pinentry' tool may not be used
6991 and the passphrases for the to be used keys are given at machine
6994 Passphrases set with this utility don't expire unless the `--forget'
6995 option is used to explicitly clear them from the cache -- or
6996 `gpg-agent' is either restarted or reloaded (by sending a SIGHUP to
6997 it). It is necessary to allow this passphrase presetting by starting
6998 `gpg-agent' with the `--allow-preset-passphrase'.
7002 * Invoking gpg-preset-passphrase:: List of all commands and options.
7005 File: gnupg.info, Node: Invoking gpg-preset-passphrase, Up: gpg-preset-passphrase
7007 7.7.1 List of all commands and options.
7008 ---------------------------------------
7010 `gpg-preset-passphrase' is invoked this way:
7012 gpg-preset-passphrase [options] [command] CACHEID
7014 CACHEID is either a 40 character keygrip of hexadecimal characters
7015 identifying the key for which the passphrase should be set or cleared.
7016 The keygrip is listed along with the key when running the command:
7017 `gpgsm --dump-secret-keys'. Alternatively an arbitrary string may be
7018 used to identify a passphrase; it is suggested that such a string is
7019 prefixed with the name of the application (e.g `foo:12346').
7021 One of the following command options must be given:
7024 Preset a passphrase. This is what you usually will use.
7025 `gpg-preset-passphrase' will then read the passphrase from `stdin'.
7028 Flush the passphrase for the given cache ID from the cache.
7031 The following additional options may be used:
7035 Output additional information while running.
7038 `--passphrase STRING'
7039 Instead of reading the passphrase from `stdin', use the supplied
7040 STRING as passphrase. Note that this makes the passphrase visible
7044 File: gnupg.info, Node: gpg-connect-agent, Next: gpgparsemail, Prev: gpg-preset-passphrase, Up: Helper Tools
7046 7.8 Communicate with a running agent.
7047 =====================================
7049 The `gpg-connect-agent' is a utility to communicate with a running
7050 `gpg-agent'. It is useful to check out the commands gpg-agent provides
7051 using the Assuan interface. It might also be useful for scripting
7052 simple applications. Input is expected at stdin and out put gets
7055 It is very similar to running `gpg-agent' in server mode; but here
7056 we connect to a running instance.
7060 * Invoking gpg-connect-agent:: List of all options.
7061 * Controlling gpg-connect-agent:: Control commands.
7064 File: gnupg.info, Node: Invoking gpg-connect-agent, Next: Controlling gpg-connect-agent, Up: gpg-connect-agent
7066 7.8.1 List of all options.
7067 --------------------------
7069 `gpg-connect-agent' is invoked this way:
7071 gpg-connect-agent [options] [commands]
7073 The following options may be used:
7077 Output additional information while running.
7082 Try to be as quiet as possible.
7085 Set the name of the home directory to DIR. If this option is not
7086 used, the home directory defaults to `~/.gnupg'. It is only
7087 recognized when given on the command line. It also overrides any
7088 home directory stated through the environment variable `GNUPGHOME'
7089 or (on W32 systems) by means of the Registry entry
7090 HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
7092 `--agent-program FILE'
7093 Specify the agent program to be started if none is running.
7097 Connect to socket NAME assuming this is an Assuan style server.
7098 Do not run any special initializations or environment checks.
7099 This may be used to directly connect to any Assuan style socket
7104 Take the rest of the command line as a program and it's arguments
7105 and execute it as an assuan server. Here is how you would run
7107 gpg-connect-agent --exec gpgsm --server
7108 Note that you may not use options on the command line in this case.
7111 When using `-S' or `--exec', `gpg-connect-agent' connects to the
7112 assuan server in extended mode to allow descriptor passing. This
7113 option makes it use the old mode.
7116 Run the commands from FILE at startup and then continue with the
7117 regular input method. Note, that commands given on the command
7118 line are executed after this file.
7122 Run the command `/subst' at startup.
7125 Print data lines in a hex format and the ASCII representation of
7126 non-control characters.
7129 Decode data lines. That is to remove percent escapes but make
7130 sure that a new line always starts with a D and a space.
7134 File: gnupg.info, Node: Controlling gpg-connect-agent, Prev: Invoking gpg-connect-agent, Up: gpg-connect-agent
7136 7.8.2 Control commands.
7137 -----------------------
7139 While reading Assuan commands, gpg-agent also allows a few special
7140 commands to control its operation. These control commands all start
7147 Set the variable NAME to VALUE. Variables are only substituted on
7148 the input if the `/subst' has been used. Variables are referenced
7149 by prefixing the name with a dollar sign and optionally include
7150 the name in curly braces. The rules for a valid name are
7151 identically to those of the standard bourne shell. This is not yet
7152 enforced but may be in the future. When used with curly braces no
7153 leading or trailing white space is allowed.
7155 If a variable is not found, it is searched in the environment and
7156 if found copied to the table of variables.
7158 Variable functions are available: The name of the function must be
7159 followed by at least one space and the at least one argument. The
7160 following functions are available:
7163 Return a value described by the argument. Available
7167 The current working directory.
7173 GnuPG's system configuration directory.
7176 GnuPG's binary directory.
7179 GnuPG's library directory.
7182 GnuPG's library directory for executable files.
7185 GnuPG's data directory.
7188 The PID of the current server. Command `/serverpid' must
7189 have been given to return a useful value.
7192 Remove C-style escapes from ARGS. Note that `\0' and `\x00'
7193 terminate the returned string implicitly. The string to be
7194 converted are the entire arguments right behind the
7195 delimiting space of the function name.
7199 Remove percent style escaping from ARGS. Note that `%00'
7200 terminates the string implicitly. The string to be converted
7201 are the entire arguments right behind the delimiting space of
7202 the function name. `unpercent+' also maps plus signs to a
7207 Escape the ARGS using percent style escaping. Tabs,
7208 formfeeds, linefeeds, carriage returns and colons are
7209 escaped. `percent+' also maps spaces to plus signs.
7214 Assume ARG is an integer and evaluate it using `strtol'.
7215 Return the gpg-error error code, error source or a formatted
7216 string with the error code and error source.
7223 Evaluate all arguments as long integers using `strtol' and
7224 apply this operator. A division by zero yields an empty
7230 Evaluate all arguments as long integers using `strtol' and
7231 apply the logical oeprators NOT, OR or AND. The NOT operator
7232 works on the last argument only.
7236 Use content of the variable VAR for inquiries with NAME. NAME may
7237 be an asterisk (`*') to match any inquiry.
7239 `/definqfile NAME FILE'
7240 Use content of FILE for inquiries with NAME. NAME may be an
7241 asterisk (`*') to match any inquiry.
7243 `/definqprog NAME PROG'
7244 Run PROG for inquiries matching NAME and pass the entire line to
7245 it as command line arguments.
7248 Write all data lines from the server to the file NAME. The file
7249 is opened for writing and created if it does not exists. An
7250 existing file is first truncated to 0. The data written to the
7251 file fully decoded. Using a single dash for NAME writes to
7252 stdout. The file is kept open until a new file is set using this
7253 command or this command is used without an argument.
7256 Print all definitions
7259 Delete all definitions
7262 Open FILE in MODE (which needs to be a valid `fopen' mode string)
7263 and send the file descriptor to the server. This is usually
7264 followed by a command like `INPUT FD' to set the input source for
7268 Not yet implemented.
7270 `/open VAR FILE [MODE]'
7271 Open FILE and assign the file descriptor to VAR. Warning: This
7272 command is experimental and might change in future versions.
7275 Close the file descriptor FD. Warning: This command is
7276 experimental and might change in future versions.
7279 Show a list of open files.
7282 Send the Assuan command `GETINFO pid' to the server and store the
7283 returned PID for internal purposes.
7290 Same as the command line option `--hex'.
7294 Same as the command line option `--decode'.
7298 Enable and disable variable substitution. It defaults to disabled
7299 unless the command line option `--subst' has been used. If /subst
7300 as been enabled once, leading whitespace is removed from input
7301 lines which makes scripts easier to read.
7305 These commands provide a way for executing loops. All lines
7306 between the `while' and the corresponding `end' are executed as
7307 long as the evaluation of CONDITION yields a non-zero value or is
7308 the string `true' or `yes'. The evaluation is done by passing
7309 CONDITION to the `strtol' function. Example:
7314 /echo loop couter is $i
7320 These commands provide a way for conditional execution. All lines
7321 between the `if' and the corresponding `end' are executed only if
7322 the evaluation of CONDITION yields a non-zero value or is the
7323 string `true' or `yes'. The evaluation is done by passing
7324 CONDITION to the `strtol' function.
7327 Run commands from FILE.
7330 Terminate the connection and the program
7333 Print a list of available control commands.
7337 File: gnupg.info, Node: gpgparsemail, Next: symcryptrun, Prev: gpg-connect-agent, Up: Helper Tools
7339 7.9 Parse a mail message into an annotated format
7340 =================================================
7342 The `gpgparsemail' is a utility currently only useful for debugging.
7343 Run it with `--help' for usage information.
7346 File: gnupg.info, Node: symcryptrun, Next: gpg-zip, Prev: gpgparsemail, Up: Helper Tools
7348 7.10 Call a simple symmetric encryption tool.
7349 =============================================
7351 Sometimes simple encryption tools are already in use for a long time and
7352 there might be a desire to integrate them into the GnuPG framework. The
7353 protocols and encryption methods might be non-standard or not even
7354 properly documented, so that a full-fledged encryption tool with an
7355 interface like gpg is not doable. `symcryptrun' provides a solution:
7356 It operates by calling the external encryption/decryption module and
7357 provides a passphrase for a key using the standard `pinentry' based
7358 mechanism through `gpg-agent'.
7360 Note, that `symcryptrun' is only available if GnuPG has been
7361 configured with `--enable-symcryptrun' at build time.
7365 * Invoking symcryptrun:: List of all commands and options.
7368 File: gnupg.info, Node: Invoking symcryptrun, Up: symcryptrun
7370 7.10.1 List of all commands and options.
7371 ----------------------------------------
7373 `symcryptrun' is invoked this way:
7375 symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE
7376 [--decrypt | --encrypt] [inputfile]
7378 For encryption, the plain text must be provided on STDIN or as the
7379 argument INPUTFILE, and the ciphertext will be output to STDOUT. For
7380 decryption vice versa.
7382 CLASS describes the calling conventions of the external tool.
7383 Currently it must be given as `confucius'. PROGRAM is the full
7384 filename of that external tool.
7386 For the class `confucius' the option `--keyfile' is required;
7387 KEYFILE is the name of a file containing the secret key, which may be
7388 protected by a passphrase. For detailed calling conventions, see the
7391 Note, that `gpg-agent' must be running before starting `symcryptrun'.
7393 The following additional options may be used:
7397 Output additional information while running.
7402 Try to be as quiet as possible.
7405 Set the name of the home directory to DIR. If this option is not
7406 used, the home directory defaults to `~/.gnupg'. It is only
7407 recognized when given on the command line. It also overrides any
7408 home directory stated through the environment variable `GNUPGHOME'
7409 or (on W32 systems) by means of the Registry entry
7410 HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
7413 Append all logging output to FILE. Default is to write logging
7414 information to STDERR.
7417 The possible exit status codes of `symcryptrun' are:
7426 No valid passphrase was provided.
7429 The operation was canceled by the user.
7433 File: gnupg.info, Node: gpg-zip, Prev: symcryptrun, Up: Helper Tools
7435 7.11 Encrypt or sign files into an archive
7436 ==========================================
7438 `gpg-zip' encrypts or signs files into an archive. It is an gpg-ized
7439 tar using the same format as used by PGP's PGP Zip.
7441 `gpg-zip' is invoked this way:
7443 gpg-zip [options] FILENAME1 [FILENAME2, ...] DIRECTORY [DIRECTORY2, ...]
7445 `gpg-zip' understands these options:
7449 Encrypt data. This option may be combined with `--symmetric' (for
7450 output that may be decrypted via a secret key or a passphrase).
7458 Encrypt with a symmetric cipher using a passphrase. The default
7459 symmetric cipher used is CAST5, but may be chosen with the
7460 `--cipher-algo' option to `gpg'.
7464 Make a signature. See `gpg'.
7468 Encrypt for user id USER. See `gpg'.
7472 Use USER as the key to sign with. See `gpg'.
7475 List the contents of the specified archive.
7479 Write output to specified file FILE.
7482 Use the specified command GPGCMD instead of `gpg'.
7485 Pass the specified options to `gpg'.
7488 Use the specified command TARCMD instead of `tar'.
7491 Pass the specified options to `tar'.
7494 Print version of the program and exit.
7497 Display a brief help page and exit.
7500 The program returns 0 if everything was fine, 1 otherwise.
7504 Encrypt the contents of directory `mydocs' for user Bob to file `test1':
7506 gpg-zip --encrypt --output test1 --gpg-args -r Bob mydocs
7508 List the contents of archive `test1':
7510 gpg-zip --list-archive test1
7513 File: gnupg.info, Node: Howtos, Next: System Notes, Prev: Helper Tools, Up: Top
7515 8 How to do certain things
7516 **************************
7518 This is a collection of small howto documents.
7522 * Howto Create a Server Cert:: Creating a TLS server certificate.
7525 File: gnupg.info, Node: Howto Create a Server Cert, Up: Howtos
7527 8.1 Creating a TLS server certificate
7528 =====================================
7530 Here is a brief run up on how to create a server certificate. It has
7531 actually been done this way to get a certificate from CAcert to be used
7532 on a real server. It has only been tested with this CA, but there
7533 shouldn't be any problem to run this against any other CA.
7535 Before you start, make sure that gpg-agent is running. As there is
7536 no need for a configuration file, you may simply enter:
7538 $ gpgsm-gencert.sh >a.p10
7542 [3] Direct from card
7546 I opted for creating a new RSA key. The other option is to use an
7547 already existing key, by selecting `2' and entering the so-called
7548 keygrip. Running the command `gpgsm --dump-secret-key USERID' shows
7549 you this keygrip. Using `3' offers another menu to create a
7550 certificate directly from a smart card based key.
7560 The script offers two common key sizes. With the current setup of
7561 CAcert, it does not make much sense to use a 2k key; their policies need
7562 to be revised anyway (a CA root key valid for 30 years is not really
7570 You selected: sign, encrypt
7572 We want to sign and encrypt using this key. This is just a suggestion
7573 and the CA may actually assign other key capabilities.
7575 Now for some real data:
7578 > CN=kerckhoffs.g10code.com
7580 This is the most important value for a server certificate. Enter here
7581 the canonical name of your server machine. You may add other virtual
7584 E-Mail addresses (end with an empty line)
7587 We don't need email addresses in a server certificate and CAcert
7588 would anyway ignore such a request. Thus just hit enter.
7590 If you want to create a client certificate for email encryption, this
7591 would be the place to enter your mail address (e.g. <joe@example.org>).
7592 You may enter as many addresses as you like, however the CA may not
7593 accept them all or reject the entire request.
7595 DNS Names (optional; end with an empty line)
7597 DNS Names (optional; end with an empty line)
7599 DNS Names (optional; end with an empty line)
7602 Here I entered the names of the servers which actually run on the
7603 machine given in the DN above. The browser will accept a certificate for
7604 any of these names. As usual the CA must approve all of these names.
7606 URIs (optional; end with an empty line)
7609 It is possible to insert arbitrary URIs into a certificate; for a
7610 server certificate this does not make sense.
7612 We have now entered all required information and `gpgsm' will
7613 display what it has gathered and ask whether to create the certificate
7616 Parameters for certificate request to create:
7619 3 Key-Usage: sign, encrypt
7620 4 Name-DN: CN=kerckhoffs.g10code.com
7621 5 Name-DNS: www.g10code.com
7622 6 Name-DNS: ftp.g10code.com
7624 Really create such a CSR?
7630 `gpgsm' will now start working on creating the request. As this
7631 includes the creation of an RSA key it may take a while. During this
7632 time you will be asked 3 times for a passphrase to protect the created
7633 private key on your system. A pop up window will appear to ask for it.
7634 The first two prompts are for the new passphrase and for re-entering it;
7635 the third one is required to actually create the certificate signing
7638 When it is ready, you should see the final notice:
7640 gpgsm: certificate request created
7642 Now, you may look at the created request:
7645 -----BEGIN CERTIFICATE REQUEST-----
7646 MIIBnzCCAQgCAQAwITEfMB0GA1UEAxMWa2VyY2tob2Zmcy5nMTBjb2RlLmNvbTCB
7647 nzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA5h+uKRenpvbe+BnMY6siPO50LVyg
7648 HtB7kr+YISlPJ5JAFO12yQFz9Y0sBLHbjR+V+TOawwP1dZhGjlgnEBkMdWKuEBlS
7649 wFTALLX78GAyvAYAmPqSPDEYXkMECyUXVX/bbGI1bY8Y2OGy4w4D+v7e+xD2NBkm
7650 Bj5cNy+YMbGVldECAwEAAaA+MDwGCSqGSIb3DQEJDjEvMC0wKwYDVR0RBCQwIoIP
7651 d3d3LmcxMGNvZGUuY29tgg9mdHAuZzEwY29kZS5jb20wDQYJKoZIhvcNAQEFBQAD
7652 gYEAzBRIi8KTfKyebOlMtDN6oDYBOv+r9A4w3u/Z1ikjffaiN1Bmd2o9Ez9KXKHA
7653 IezLeSEA/rGUPN5Ur5qIJnRNQ8xrS+iLftr8msWQSZppVnA/vnqMrtqBUpitqAr0
7654 eYBmt1Uem2Y3UFABrKPglv2xzgGkrKX6AqmFoOnJWQ0QcTw=
7655 -----END CERTIFICATE REQUEST-----
7658 You may now proceed by logging into your account at the CAcert
7659 website, choose `Server Certificates - New', check `sign by class 3 root
7660 certificate', paste the above request block into the text field and
7663 If everything works out fine, a certificate will be shown. Now run
7667 and paste the certificate from the CAcert page into your terminal
7668 followed by a Ctrl-D
7670 -----BEGIN CERTIFICATE-----
7671 MIIEIjCCAgqgAwIBAgIBTDANBgkqhkiG9w0BAQQFADBUMRQwEgYDVQQKEwtDQWNl
7672 cnQgSW5jLjEeMBwGA1UECxMVaHR0cDovL3d3dy5DQWNlcnQub3JnMRwwGgYDVQQD
7673 ExNDQWNlcnQgQ2xhc3MgMyBSb290MB4XDTA1MTAyODE2MjA1MVoXDTA3MTAyODE2
7674 MjA1MVowITEfMB0GA1UEAxMWa2VyY2tob2Zmcy5nMTBjb2RlLmNvbTCBnzANBgkq
7675 hkiG9w0BAQEFAAOBjQAwgYkCgYEA5h+uKRenpvbe+BnMY6siPO50LVygHtB7kr+Y
7676 ISlPJ5JAFO12yQFz9Y0sBLHbjR+V+TOawwP1dZhGjlgnEBkMdWKuEBlSwFTALLX7
7677 8GAyvAYAmPqSPDEYXkMECyUXVX/bbGI1bY8Y2OGy4w4D+v7e+xD2NBkmBj5cNy+Y
7678 MbGVldECAwEAAaOBtTCBsjAMBgNVHRMBAf8EAjAAMDQGA1UdJQQtMCsGCCsGAQUF
7679 BwMCBggrBgEFBQcDAQYJYIZIAYb4QgQBBgorBgEEAYI3CgMDMAsGA1UdDwQEAwIF
7680 oDAyBggrBgEFBQcBAQQmMCQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLmNhY2Vy
7681 dC5vcmcwKwYDVR0RBCQwIoIPd3d3LmcxMGNvZGUuY29tgg9mdHAuZzEwY29kZS5j
7682 b20wDQYJKoZIhvcNAQEEBQADggIBAAj5XAHCtzQR8PV6PkQBgZqUCbcfxGO/ZIp9
7683 aIT6J2z0Jo1OZI6KmConbqnZG9WyDlV5P7msQXW/Z9nBfoj4KSmNR8G/wtb8ClJn
7684 W8s75+K3ZLq1UgEyxBDrS7GjtbVaj7gsfZsuiQzxmk9lbl1gbkpJ3VEMjwVCTMlM
7685 fpjp8etyPhUZqOZaoKVaq//KTOsjhPMwz7TcfOkHvXketPrWTcefJQU7NKLH16D3
7686 mZAwnBxp3P51H6E6VG8AoJO8xCBuVwsbXKEf/FW+tmKG9pog6CaZQ9WibROTtnKj
7687 NJjSBsrUk5C+JowO/EyZRGm6R1tlok8iFXj+2aimyeBqDcxozNmFgh9F3S5u0wK0
7688 6cfYgkPVMHxgwV3f3Qh+tJkgLExN7KfO9hvpZqAh+CLQtxVmvpxEVEXKR6nwBI5U
7689 BaseulvVy3wUfg2daPkG17kDDBzQlsWC0BRF8anH+FWSrvseC3nS0a9g3sXF1Ic3
7690 gIqeAMhkant1Ac3RR6YCWtJKr2rcQNdDAxXK35/gUSQNCi9dclEzoOgjziuA1Mha
7691 94jYcvGKcwThn0iITVS5hOsCfaySBLxTzfIruLbPxXlpWuCW/6I/7YyivppKgEZU
7692 rUTFlNElRXCwIl0YcJkIaYYqWf7+A/aqYJCi8+51usZwMy3Jsq3hJ6MA3h1BgwZs
7694 -----END CERTIFICATE-----
7695 gpgsm: issuer certificate (#/CN=CAcert Class 3 Ro[...]) not found
7696 gpgsm: certificate imported
7698 gpgsm: total number processed: 1
7701 gpgsm tells you that it has imported the certificate. It is now
7702 associated with the key you used when creating the request. The root
7703 certificate has not been found, so you may want to import it from the
7706 To see the content of your certificate, you may now enter:
7708 $ gpgsm -K kerckhoffs.g10code.com
7709 /home/foo/.gnupg/pubring.kbx
7710 ---------------------------
7712 Issuer: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.[...]
7713 Subject: /CN=kerckhoffs.g10code.com
7714 aka: (dns-name www.g10code.com)
7715 aka: (dns-name ftp.g10code.com)
7716 validity: 2005-10-28 16:20:51 through 2007-10-28 16:20:51
7717 key type: 1024 bit RSA
7718 key usage: digitalSignature keyEncipherment
7719 ext key usage: clientAuth (suggested), serverAuth (suggested), [...]
7720 fingerprint: 0F:9C:27:B2:DA:05:5F:CB:33:19:D8:E9:65:B9:BD:4F:B1:98:CC:57
7722 I used `-K' above because this will only list certificates for which
7723 a private key is available. To see more details, you may use
7724 `--dump-secret-keys' instead of `-K'.
7726 To make actual use of the certificate you need to install it on your
7727 server. Server software usually expects a PKCS\#12 file with key and
7728 certificate. To create such a file, run:
7730 $ gpgsm --export-secret-key-p12 -a >kerckhoffs-cert.pem
7732 You will be asked for the passphrase as well as for a new passphrase
7733 to be used to protect the PKCS\#12 file. The file now contains the
7734 certificate as well as the private key:
7736 $ cat kerckhoffs-cert.pem
7737 Issuer ...: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.CA[...]
7739 Subject ..: /CN=kerckhoffs.g10code.com
7740 aka ..: (dns-name www.g10code.com)
7741 aka ..: (dns-name ftp.g10code.com)
7743 -----BEGIN PKCS12-----
7744 MIIHlwIBAzCCB5AGCSqGSIb37QdHAaCCB4EEggd9MIIHeTk1BJ8GCSqGSIb3DQEu
7745 [...many more lines...]
7746 -----END PKCS12-----
7749 Copy this file in a secure way to the server, install it there and
7750 delete the file then. You may export the file again at any time as long
7751 as it is available in GnuPG's private key database.
projects / platform / upstream / gpg2.git / blob