« back to all changes in this revision
Viewing changes to doc/gnupg.info-1
- browse files at revision 6
- compare with another revision
- download diff
- download tarball
- view history from revision 6
- Committer: Bazaar Package Importer
- Author(s): Thomas Viehmann
- Date: 2008-10-04 10:25:53 UTC
- mfrom: (5.1.15 intrepid)
- Revision ID: james.westby@ubuntu.com-20081004102553-fv62pp8dsitxli47
Tags: 2.0.9-3.1
* Non-maintainer upload.
* agent/gpg-agent.c: Deinit the threading library before exec'ing
the command to run in --daemon mode. And because that still doesn't
restore the sigprocmask, do that manually. Closes: #499569
* agent/gpg-agent.c: Deinit the threading library before exec'ing
the command to run in --daemon mode. And because that still doesn't
restore the sigprocmask, do that manually. Closes: #499569
- files added:
- COPYING.LIB
- doc/examples
- tests/openpgp
- files removed:
- BUGS
- artwork
- assuan
- checks
- cipher
- contrib
- doc/fr
- doc/gph
- intl
- mpi
- mpi/alpha
- mpi/generic
- mpi/hppa
- mpi/hppa1.1
- mpi/i386
- mpi/i386-openbsd
- mpi/i586
- mpi/m68k
- mpi/m68k/mc68020
- mpi/mips3
- mpi/pa7100
- mpi/power
- mpi/powerpc32
- mpi/powerpc64
- mpi/sparc32
- mpi/sparc32v8
- mpi/supersparc
- scripts/conf-riscos
- scripts/conf-riscos/cipher
- scripts/conf-riscos/include
- tests/extrasamples
- tests/samplemsgs
- util
- zlib
- files modified:
- ABOUT-NLS
- tests/inittests *
- tests/pkits/runtest *
- tests/runtest *
- tools/addgnupghome *
added
removed
doc/gnupg.info-1
1
This is gnupg.info, produced by makeinfo version 4.8 from gnupg.texi.
2
3
This is the `The GNU Privacy Guard Manual' (version 2.0.9,
4
March 2008).
5
6
Copyright (C) 2002, 2004, 2005, 2006, 2007 Free Software Foundation,
7
Inc.
8
9
Permission is granted to copy, distribute and/or modify this
10
document under the terms of the GNU General Public License as
11
published by the Free Software Foundation; either version 3 of the
12
License, or (at your option) any later version. The text of the
13
license can be found in the section entitled "Copying".
14
15
INFO-DIR-SECTION GNU Utilities
16
START-INFO-DIR-ENTRY
17
* gpg2: (gnupg). OpenPGP encryption and signing tool.
18
* gpgsm: (gnupg). S/MIME encryption and signing tool.
19
END-INFO-DIR-ENTRY
20
21
22
File: gnupg.info, Node: Top, Next: Installation, Up: (dir)
23
24
Using the GNU Privacy Guard
25
***************************
26
27
This is the `The GNU Privacy Guard Manual' (version 2.0.9, March 2008).
28
29
Copyright (C) 2002, 2004, 2005, 2006, 2007 Free Software Foundation,
30
Inc.
31
32
Permission is granted to copy, distribute and/or modify this
33
document under the terms of the GNU General Public License as
34
published by the Free Software Foundation; either version 3 of the
35
License, or (at your option) any later version. The text of the
36
license can be found in the section entitled "Copying".
37
38
This manual documents how to use the GNU Privacy Guard system as
39
well as the administration and the architecture.
40
41
* Menu:
42
43
* Installation:: A short installation guide.
44
45
* Invoking GPG-AGENT:: How to launch the secret key daemon.
46
* Invoking GPG:: Using the OpenPGP protocol.
47
* Invoking GPGSM:: Using the S/MIME protocol.
48
* Invoking SCDAEMON:: How to handle Smartcards.
49
* Specify a User ID:: How to Specify a User Id.
50
51
* Helper Tools:: Description of small helper tools
52
53
* Howtos:: How to do certain things.
54
* System Notes:: Notes pertaining to certain OSes.
55
* Debugging:: How to solve problems
56
57
* Copying:: GNU General Public License says
58
how you can copy and share GnuPG
59
* Contributors:: People who have contributed to GnuPG.
60
61
* Glossary:: Short description of terms used.
62
* Option Index:: Index to command line options.
63
* Index:: Index of concepts and symbol names.
64
65
66
File: gnupg.info, Node: Installation, Next: Invoking GPG-AGENT, Prev: Top, Up: Top
67
68
1 A short installation guide.
69
*****************************
70
71
Unfortunately the installation guide has not been finished in time.
72
Instead of delaying the release of GnuPG 2.0 even further, I decided to
73
release without that guide. The chapter on gpg-agent and gpgsm do
74
include brief information on how to set up the whole thing. Please
75
watch the GnuPG website for updates of the documentation. In the
76
meantime you may search the GnuPG mailing list archives or ask on the
77
gnupg-users mailing listsfor advise on how to solve problems or how to
78
get that whole thing up and running.
79
80
Such questions may also help to write a proper installation guide.
81
82
[to be written]
83
84
XXX Tell how to setup the system, install certificates, how dirmngr
85
relates to GnuPG etc.
86
87
** Explain how to setup a root CA key as trusted
88
89
X.509 is based on a hierarchical key infrastructure. At the root of
90
the tree a trusted anchor (root certificate) is required. There are
91
usually no other means of verifying whether this root certificate is
92
trustworthy than looking it up in a list. GnuPG uses a file
93
(`trustlist.txt') to keep track of all root certificates it knows
94
about. There are 3 ways to get certificates into this list:
95
96
* Use the list which comes with GnuPG. However this list only
97
contains a few root certifciates. Most installations will need
98
more.
99
100
* Let `gpgsm' ask you whether you want to insert a new root
101
certificate. To enable this feature you need to set the option
102
`allow-mark-trusted' into `gpg-agent.conf'. In general it is not
103
a good idea to do it this way. Checking whether a root
104
certificate is really trustworthy requires a decsions, which casual
105
usuers are not up to. Thus, by default this option is not enabled.
106
107
* Manually maintain the list of trusted root certificates. For a
108
multi user installation this can be done once for all users on a
109
machine. Specific changes on a per-user base are also possible.
110
111
XXX decribe how to maintain trustlist.txt and
112
/etc/gnupg/trustlist.txt.
113
114
** How to get the ssh support running
115
116
XXX How to use the ssh support.
117
118
1.1 Installation Overview
119
=========================
120
121
XXXX
122
123
124
File: gnupg.info, Node: Invoking GPG-AGENT, Next: Invoking GPG, Prev: Installation, Up: Top
125
126
2 Invoking GPG-AGENT
127
********************
128
129
`gpg-agent' is a daemon to manage secret (private) keys independently
130
from any protocol. It is used as a backend for `gpg' and `gpgsm' as
131
well as for a couple of other utilities.
132
133
The usual way to run the agent is from the `~/.xsession' file:
134
135
eval `gpg-agent --daemon`
136
137
If you don't use an X server, you can also put this into your regular
138
startup file `~/.profile' or `.bash_profile'. It is best not to run
139
multiple instance of the `gpg-agent', so you should make sure that only
140
one is running: `gpg-agent' uses an environment variable to inform
141
clients about the communication parameters. You can write the content
142
of this environment variable to a file so that you can test for a
143
running agent. This short script may do the job:
144
145
if test -f $HOME/.gpg-agent-info && \
146
kill -0 `cut -d: -f 2 $HOME/.gpg-agent-info` 2>/dev/null; then
147
GPG_AGENT_INFO=`cat $HOME/.gpg-agent-info`
148
export GPG_AGENT_INFO
149
else
150
eval `gpg-agent --daemon`
151
echo $GPG_AGENT_INFO >$HOME/.gpg-agent-info
152
fi
153
154
Note that the new option `--write-env-file' may be used instead.
155
156
You should always add the following lines to your `.bashrc' or whatever
157
initialization file is used for all shell invocations:
158
159
GPG_TTY=`tty`
160
export GPG_TTY
161
162
It is important that this environment variable always reflects the
163
output of the `tty' command. For W32 systems this option is not
164
required.
165
166
Please make sure that a proper pinentry program has been installed
167
under the default filename (which is system dependant) or use the
168
option `pinentry-program' to specify the full name of that program. It
169
is often useful to install a symbolic link from the actual used
170
pinentry (e.g. `/usr/bin/pinentry-gtk') to the expected one (e.g.
171
`/usr/bin/pinentry').
172
173
*Note Option Index::,for an index to `GPG-AGENT''s commands and options.
174
175
* Menu:
176
177
* Agent Commands:: List of all commands.
178
* Agent Options:: List of all options.
179
* Agent Configuration:: Configuration files.
180
* Agent Signals:: Use of some signals.
181
* Agent Examples:: Some usage examples.
182
* Agent Protocol:: The protocol the agent uses.
183
184
185
File: gnupg.info, Node: Agent Commands, Next: Agent Options, Up: Invoking GPG-AGENT
186
187
2.1 Commands
188
============
189
190
Commands are not distinguished from options except for the fact that
191
only one command is allowed.
192
193
`--version'
194
Print the program version and licensing information. Not that you
195
can abbreviate this command.
196
197
`--help'
198
`-h'
199
Print a usage message summarizing the most useful command-line
200
options. Not that you can abbreviate this command.
201
202
`--dump-options'
203
Print a list of all available options and commands. Not that you
204
can abbreviate this command.
205
206
`--server'
207
Run in server mode and wait for commands on the `stdin'. The
208
default mode is to create a socket and listen for commands there.
209
210
`--daemon [COMMAND LINE]'
211
Run the program in the background. This option is required to
212
prevent it from being accidently running in the background. A
213
common way to do this is:
214
$ eval `gpg-agent -daemon`
215
216
217
File: gnupg.info, Node: Agent Options, Next: Agent Configuration, Prev: Agent Commands, Up: Invoking GPG-AGENT
218
219
2.2 Option Summary
220
==================
221
222
`--options FILE'
223
Reads configuration from FILE instead of from the default per-user
224
configuration file. The default configuration file is named
225
`gpg-agent.conf' and expected in the `.gnupg' directory directly
226
below the home directory of the user.
227
228
`--homedir DIR'
229
Set the name of the home directory to DIR. If his option is not
230
used, the home directory defaults to `~/.gnupg'. It is only
231
recognized when given on the command line. It also overrides any
232
home directory stated through the environment variable `GNUPGHOME'
233
or (on W32 systems) by means on the Registry entry
234
HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
235
236
`-v'
237
238
`--verbose'
239
Outputs additional information while running. You can increase
240
the verbosity by giving several verbose commands to `gpgsm', such
241
as `-vv'.
242
243
`-q'
244
245
`--quiet'
246
Try to be as quiet as possible.
247
248
`--batch'
249
Don't invoke a pinentry or do any other thing requiring human
250
interaction.
251
252
`--faked-system-time EPOCH'
253
This option is only useful for testing; it sets the system time
254
back or forth to EPOCH which is the number of seconds elapsed
255
since the year 1970.
256
257
`--debug-level LEVEL'
258
Select the debug level for investigating problems. LEVEL may be
259
one of:
260
261
`none'
262
no debugging at all.
263
264
`basic'
265
some basic debug messages
266
267
`advanced'
268
more verbose debug messages
269
270
`expert'
271
even more detailed messages
272
273
`guru'
274
all of the debug messages you can get
275
276
How these messages are mapped to the actual debugging flags is not
277
specified and may change with newer releases of this program. They
278
are however carefully selected to best aid in debugging.
279
280
`--debug FLAGS'
281
This option is only useful for debugging and the behaviour may
282
change at any time without notice. FLAGS are bit encoded and may
283
be given in usual C-Syntax. The currently defined bits are:
284
285
`0 (1)'
286
X.509 or OpenPGP protocol related data
287
288
`1 (2)'
289
values of big number integers
290
291
`2 (4)'
292
low level crypto operations
293
294
`5 (32)'
295
memory allocation
296
297
`6 (64)'
298
caching
299
300
`7 (128)'
301
show memory statistics.
302
303
`9 (512)'
304
write hashed data to files named `dbgmd-000*'
305
306
`10 (1024)'
307
trace Assuan protocol
308
309
`12 (4096)'
310
bypass all certificate validation
311
312
`--debug-all'
313
Same as `--debug=0xffffffff'
314
315
`--debug-wait N'
316
When running in server mode, wait N seconds before entering the
317
actual processing loop and print the pid. This gives time to
318
attach a debugger.
319
320
`--no-detach'
321
Don't detach the process from the console. This is mainly useful
322
for debugging.
323
324
`-s'
325
`--sh'
326
`-c'
327
`--csh'
328
Format the info output in daemon mode for use with the standard
329
Bourne shell or the C-shell respectively. The default is to guess
330
it based on the environment variable `SHELL' which is correct in
331
almost all cases.
332
333
`--write-env-file FILE'
334
Often it is required to connect to the agent from a process not
335
being an inferior of `gpg-agent' and thus the environment variable
336
with the socket name is not available. To help setting up those
337
variables in other sessions, this option may be used to write the
338
information into FILE. If FILE is not specified the default name
339
`${HOME}/.gpg-agent-info' will be used. The format is suitable to
340
be evaluated by a Bourne shell like in this simple example:
341
342
eval `cat FILE`
343
eval `cut -d= -f 1 < FILE | xargs echo export`
344
345
`--no-grab'
346
Tell the pinentry not to grab the keyboard and mouse. This option
347
should in general not be used to avoid X-sniffing attacks.
348
349
`--log-file FILE'
350
Append all logging output to FILE. This is very helpful in seeing
351
what the agent actually does.
352
353
`--allow-mark-trusted'
354
Allow clients to mark keys as trusted, i.e. put them into the
355
`trustlist.txt' file. This is by default not allowed to make it
356
harder for users to inadvertently accept Root-CA keys.
357
358
`--ignore-cache-for-signing'
359
This option will let `gpg-agent' bypass the passphrase cache for
360
all signing operation. Note that there is also a per-session
361
option to control this behaviour but this command line option
362
takes precedence.
363
364
`--default-cache-ttl N'
365
Set the time a cache entry is valid to N seconds. The default is
366
600 seconds.
367
368
`--default-cache-ttl-ssh N'
369
Set the time a cache entry used for SSH keys is valid to N
370
seconds. The default is 1800 seconds.
371
372
`--max-cache-ttl N'
373
Set the maximum time a cache entry is valid to N seconds. After
374
this time a cache entry will be expired even if it has been
375
accessed recently. The default is 2 hours (7200 seconds).
376
377
`--max-cache-ttl-ssh N'
378
Set the maximum time a cache entry used for SSH keys is valid to N
379
seconds. After this time a cache entry will be expired even if it
380
has been accessed recently. The default is 2 hours (7200 seconds).
381
382
`--enforce-passphrase-constraints'
383
Enforce the passphrase constraints by not allowing the user to
384
bypass them using the "Take it anyway" button.
385
386
`--min-passphrase-len N'
387
Set the minimal length of a passphrase. When entering a new
388
passphrase shorter than this value a warning will be displayed.
389
Defaults to 8.
390
391
`--min-passphrase-nonalpha N'
392
Set the minimal number of digits or special characters required in
393
a passphrase. When entering a new passphrase with less than this
394
number of digits or special characters a warning will be
395
displayed. Defaults to 1.
396
397
`--check-passphrase-pattern FILE'
398
Check the passphrase against the pattern given in FILE. When
399
entering a new passphrase matching one of these pattern a warning
400
will be displayed. FILE should be an absolute filename. The
401
default is not to use any pattern file.
402
403
Security note: It is known that checking a passphrase against a
404
list of pattern or even against a complete dictionary is not very
405
effective to enforce good passphrases. Users will soon figure up
406
ways to bypass such a policy. A better policy is to educate users
407
on good security behavior and optionally to run a passphrase
408
cracker regularly on all users passphrases to catch the very
409
simple ones.
410
411
`--max-passphrase-days N'
412
Ask the user to change the passphrase if N days have passed since
413
the last change. With `--enforce-passphrase-constraints' set the
414
user may not bypass this check.
415
416
`--enable-passphrase-history'
417
This option does nothing yet.
418
419
`--pinentry-program FILENAME'
420
Use program FILENAME as the PIN entry. The default is installation
421
dependent and can be shown with the `--version' command.
422
423
`--pinentry-touch-file FILENAME'
424
By default the filename of the socket gpg-agent is listening for
425
requests is passed to Pinentry, so that it can touch that file
426
before exiting (it does this only in curses mode). This option
427
changes the file passed to Pinentry to FILENAME. The special name
428
`/dev/null' may be used to completely disable this feature. Note
429
that Pinentry will not create that file, it will only change the
430
modification and access time.
431
432
`--scdaemon-program FILENAME'
433
Use program FILENAME as the Smartcard daemon. The default is
434
installation dependent and can be shown with the `--version'
435
command.
436
437
`--disable-scdaemon'
438
Do not make use of the scdaemon tool. This option has the effect
439
of disabling the ability to do smartcard operations. Note, that
440
enabling this option at runtime does not kill an already forked
441
scdaemon.
442
443
`--use-standard-socket'
444
`--no-use-standard-socket'
445
By enabling this option `gpg-agent' will listen on the socket
446
named `S.gpg-agent', located in the home directory, and not create
447
a random socket below a temporary directory. Tools connecting to
448
`gpg-agent' should first try to connect to the socket given in
449
environment variable GPG_AGENT_INFO and then fall back to this
450
socket. This option may not be used if the home directory is
451
mounted as a remote file system. Note, that
452
`--use-standard-socket' is the default on Windows systems.
453
454
`--display STRING'
455
`--ttyname STRING'
456
`--ttytype STRING'
457
`--lc-type STRING'
458
`--lc-messages STRING'
459
`--xauthority STRING'
460
These options are used with the server mode to pass localization
461
information.
462
463
`--keep-tty'
464
`--keep-display'
465
Ignore requests to change the current `tty' or X window system's
466
`DISPLAY' variable respectively. This is useful to lock the
467
pinentry to pop up at the `tty' or display you started the agent.
468
469
`--enable-ssh-support'
470
Enable emulation of the OpenSSH Agent protocol.
471
472
In this mode of operation, the agent does not only implement the
473
gpg-agent protocol, but also the agent protocol used by OpenSSH
474
(through a separate socket). Consequently, it should be possible
475
to use the gpg-agent as a drop-in replacement for the well known
476
ssh-agent.
477
478
SSH Keys, which are to be used through the agent, need to be added
479
to the gpg-agent initially through the ssh-add utility. When a
480
key is added, ssh-add will ask for the password of the provided
481
key file and send the unprotected key material to the agent; this
482
causes the gpg-agent to ask for a passphrase, which is to be used
483
for encrypting the newly received key and storing it in a
484
gpg-agent specific directory.
485
486
Once a key has been added to the gpg-agent this way, the gpg-agent
487
will be ready to use the key.
488
489
Note: in case the gpg-agent receives a signature request, the user
490
might need to be prompted for a passphrase, which is necessary for
491
decrypting the stored key. Since the ssh-agent protocol does not
492
contain a mechanism for telling the agent on which
493
display/terminal it is running, gpg-agent's ssh-support will use
494
the TTY or X display where gpg-agent has been started. To switch
495
this display to the current one, the following command may be used:
496
497
echo UPDATESTARTUPTTY | gpg-connect-agent
498
499
500
All the long options may also be given in the configuration file
501
after stripping off the two leading dashes.
502
503
504
File: gnupg.info, Node: Agent Configuration, Next: Agent Signals, Prev: Agent Options, Up: Invoking GPG-AGENT
505
506
2.3 Configuration
507
=================
508
509
There are a few configuration files needed for the operation of the
510
agent. By default they may all be found in the current home directory
511
(*note option --homedir::).
512
513
`gpg-agent.conf'
514
This is the standard configuration file read by `gpg-agent' on
515
startup. It may contain any valid long option; the leading two
516
dashes may not be entered and the option may not be abbreviated.
517
This file is also read after a `SIGHUP' however only a few
518
options will actually have an effect. This default name may be
519
changed on the command line (*note option --options::).
520
521
`trustlist.txt'
522
This is the list of trusted keys. Comment lines, indicated by a
523
leading hash mark, as well as empty lines are ignored. To mark
524
a key as trusted you need to enter its fingerprint followed by a
525
space and a capital letter `S'. Colons may optionally be used
526
to separate the bytes of a fingerprint; this allows to cut and
527
paste the fingerprint from a key listing output.
528
529
Here is an example where two keys are marked as ultimately trusted:
530
531
# CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
532
A6935DD34EF3087973C706FC311AA2CCF733765B S
533
534
# CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
535
DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S
536
537
Before entering a key into this file, you need to ensure its
538
authenticity. How to do this depends on your organisation; your
539
administrator might have already entered those keys which are
540
deemed trustworthy enough into this file. Places where to look
541
for the fingerprint of a root certificate are letters received
542
from the CA or the website of the CA (after making 100% sure that
543
this is indeed the website of that CA). You may want to consider
544
allowing interactive updates of this file by using the *Note
545
option --allow-mark-trusted::. This is however not as secure as
546
maintaining this file manually. It is even advisable to change
547
the permissions to read-only so that this file can't be changed
548
inadvertently.
549
550
As a special feature a line `include-default' will include a global
551
list of trusted certificates (e.g. `/etc/gnupg/trustlist.txt').
552
This global list is also used if the local list is not available.
553
554
It is possible to add further flags after the `S' for use by the
555
caller:
556
557
`relax'
558
Relax checking of some root certificate requirements. This
559
is for example required if the certificate is missing the
560
basicConstraints attribute (despite that it is a MUST for CA
561
certificates).
562
563
`cm'
564
If validation of a certificate finally issued by a CA with
565
this flag set fails, try again using the chain validation
566
model.
567
568
569
`sshcontrol'
570
This file is used when support for the secure shell agent protocol
571
has been enabled (*note option --enable-ssh-support::). Only keys
572
present in this file are used in the SSH protocol. The `ssh-add'
573
tool may be used to add new entries to this file; you may also add
574
them manually. Comment lines, indicated by a leading hash mark,
575
as well as empty lines are ignored. An entry starts with optional
576
whitespace, followed by the keygrip of the key given as 40 hex
577
digits, optionally followed by the caching TTL in seconds and
578
another optional field for arbitrary flags. The keygrip may be
579
prefixed with a `!' to disable this entry.
580
581
The following example lists exactly one key. Note that keys
582
available through a OpenPGP smartcard in the active smartcard
583
reader are implicitly added to this list; i.e. there is no need to
584
list them.
585
586
# Key added on 2005-02-25 15:08:29
587
5A6592BF45DC73BD876874A28FD4639282E29B52 0
588
589
`private-keys-v1.d/'
590
This is the directory where gpg-agent stores the private keys.
591
Each key is stored in a file with the name made up of the
592
keygrip and the suffix `key'.
593
594
595
Note that on larger installations, it is useful to put predefined
596
files into the directory `/etc/skel/.gnupg/' so that newly created
597
users start up with a working configuration. For existing users the a
598
small helper script is provided to create these files (*note
599
addgnupghome::).
600
601
602
File: gnupg.info, Node: Agent Signals, Next: Agent Examples, Prev: Agent Configuration, Up: Invoking GPG-AGENT
603
604
2.4 Use of some signals.
605
========================
606
607
A running `gpg-agent' may be controlled by signals, i.e. using the
608
`kill' command to send a signal to the process.
609
610
Here is a list of supported signals:
611
612
`SIGHUP'
613
This signal flushes all cached passphrases and if the program has
614
been started with a configuration file, the configuration file is
615
read again. Only certain options are honored: `quiet', `verbose',
616
`debug', `debug-all', `debug-level', `no-grab',
617
`pinentry-program', `default-cache-ttl', `max-cache-ttl',
618
`ignore-cache-for-signing', `allow-mark-trusted' and
619
`disable-scdaemon'. `scdaemon-program' is also supported but due
620
to the current implementation, which calls the scdaemon only once,
621
it is not of much use unless you manually kill the scdaemon.
622
623
`SIGTERM'
624
Shuts down the process but waits until all current requests are
625
fulfilled. If the process has received 3 of these signals and
626
requests are still pending, a shutdown is forced.
627
628
`SIGINT'
629
Shuts down the process immediately.
630
631
`SIGUSR1'
632
Dump internal information to the log file.
633
634
`SIGUSR2'
635
This signal is used for internal purposes.
636
637
638
639
File: gnupg.info, Node: Agent Examples, Next: Agent Protocol, Prev: Agent Signals, Up: Invoking GPG-AGENT
640
641
2.5 Examples
642
============
643
644
The usual way to invoke `gpg-agent' is
645
646
$ eval `gpg-agent --daemon`
647
648
An alternative way is by replacing `ssh-agent' with `gpg-agent'. If
649
for example `ssh-agent' is started as part of the Xsession
650
initialization, you may simply replace `ssh-agent' by a script like:
651
652
#!/bin/sh
653
654
exec /usr/local/bin/gpg-agent --enable-ssh-support --daemon \
655
--write-env-file ${HOME}/.gpg-agent-info "$@"
656
657
and add something like (for Bourne shells)
658
659
if [ -f "${HOME}/.gpg-agent-info" ]; then
660
. "${HOME}/.gpg-agent-info"
661
export GPG_AGENT_INFO
662
export SSH_AUTH_SOCK
663
export SSH_AGENT_PID
664
fi
665
666
to your shell initialization file (e.g. `~/.bashrc').
667
668
669
File: gnupg.info, Node: Agent Protocol, Prev: Agent Examples, Up: Invoking GPG-AGENT
670
671
2.6 Agent's Assuan Protocol
672
===========================
673
674
Note: this section does only document the protocol, which is used by
675
GnuPG components; it does not deal with the ssh-agent protocol.
676
677
The `gpg-agent' should be started by the login shell and set an
678
environment variable to tell clients about the socket to be used.
679
Clients should deny to access an agent with a socket name which does
680
not match its own configuration. An application may choose to start an
681
instance of the gpgagent if it does not figure that any has been
682
started; it should not do this if a gpgagent is running but not usable.
683
Because `gpg-agent' can only be used in background mode, no special
684
command line option is required to activate the use of the protocol.
685
686
To identify a key we use a thing called keygrip which is the SHA-1
687
hash of an canoncical encoded S-Expression of the the public key as
688
used in Libgcrypt. For the purpose of this interface the keygrip is
689
given as a hex string. The advantage of using this and not the hash of
690
a certificate is that it will be possible to use the same keypair for
691
different protocols, thereby saving space on the token used to keep the
692
secret keys.
693
694
* Menu:
695
696
* Agent PKDECRYPT:: Decrypting a session key
697
* Agent PKSIGN:: Signing a Hash
698
* Agent GENKEY:: Generating a Key
699
* Agent IMPORT:: Importing a Secret Key
700
* Agent EXPORT:: Exporting a Secret Key
701
* Agent ISTRUSTED:: Importing a Root Certificate
702
* Agent GET_PASSPHRASE:: Ask for a passphrase
703
* Agent GET_CONFIRMATION:: Ask for confirmation
704
* Agent HAVEKEY:: Check whether a key is available
705
* Agent LEARN:: Register a smartcard
706
* Agent PASSWD:: Change a Passphrase
707
* Agent UPDATESTARTUPTTY:: Change the Standard Display
708
* Agent GETEVENTCOUNTER:: Get the Event Counters
709
* Agent GETINFO:: Return information about the process
710
711
712
File: gnupg.info, Node: Agent PKDECRYPT, Next: Agent PKSIGN, Up: Agent Protocol
713
714
2.6.1 Decrypting a session key
715
------------------------------
716
717
The client asks the server to decrypt a session key. The encrypted
718
session key should have all information needed to select the
719
appropriate secret key or to delegate it to a smartcard.
720
721
SETKEY <keyGrip>
722
723
Tell the server about the key to be used for decryption. If this is
724
not used, `gpg-agent' may try to figure out the key by trying to
725
decrypt the message with each key available.
726
727
PKDECRYPT
728
729
The agent checks whether this command is allowed and then does an
730
INQUIRY to get the ciphertext the client should then send the cipher
731
text.
732
733
S: INQUIRE CIPHERTEXT
734
C: D (xxxxxx
735
C: D xxxx)
736
C: END
737
738
Please note that the server may send status info lines while reading
739
the data lines from the client. The data send is a SPKI like S-Exp with
740
this structure:
741
742
(enc-val
743
(<algo>
744
(<param_name1> <mpi>)
745
...
746
(<param_namen> <mpi>)))
747
748
Where algo is a string with the name of the algorithm; see the
749
libgcrypt documentation for a list of valid algorithms. The number and
750
names of the parameters depend on the algorithm. The agent does return
751
an error if there is an inconsistency.
752
753
If the decryption was successful the decrypted data is returned by
754
means of "D" lines.
755
756
Here is an example session:
757
758
C: PKDECRYPT
759
S: INQUIRE CIPHERTEXT
760
C: D (enc-val elg (a 349324324)
761
C: D (b 3F444677CA)))
762
C: END
763
S: # session key follows
764
S: D (value 1234567890ABCDEF0)
765
S: OK descryption successful
766
767
768
File: gnupg.info, Node: Agent PKSIGN, Next: Agent GENKEY, Prev: Agent PKDECRYPT, Up: Agent Protocol
769
770
2.6.2 Signing a Hash
771
--------------------
772
773
The client ask the agent to sign a given hash value. A default key
774
will be chosen if no key has been set. To set a key a client first
775
uses:
776
777
SIGKEY <keyGrip>
778
779
This can be used multiple times to create multiple signature, the
780
list of keys is reset with the next PKSIGN command or a RESET. The
781
server test whether the key is a valid key to sign something and
782
responds with okay.
783
784
SETHASH --hash=<name>|<algo> <hexstring>
785
786
The client can use this command to tell the server about the data
787
<hexstring> (which usually is a hash) to be signed. <algo> is the
788
decimal encoded hash algorithm number as used by Libgcrypt. Either
789
<algo> or -hash=<name> must be given. Valid names for <name> are:
790
791
`sha1'
792
793
`sha256'
794
795
`rmd160'
796
797
`md5'
798
799
`tls-md5sha1'
800
801
The actual signing is done using
802
803
PKSIGN <options>
804
805
Options are not yet defined, but my later be used to choosen among
806
different algorithms. The agent does then some checks, asks for the
807
passphrase and as a result the server returns the signature as an SPKI
808
like S-expression in "D" lines:
809
810
(sig-val
811
(<algo>
812
(<param_name1> <mpi>)
813
...
814
(<param_namen> <mpi>)))
815
816
The operation is affected by the option
817
818
OPTION use-cache-for-signing=0|1
819
820
The default of `1' uses the cache. Setting this option to `0' will
821
lead `gpg-agent' to ignore the passphrase cache. Note, that there is
822
also a global command line option for `gpg-agent' to globally disable
823
the caching.
824
825
Here is an example session:
826
827
C: SIGKEY <keyGrip>
828
S: OK key available
829
C: SIGKEY <keyGrip>
830
S: OK key available
831
C: PKSIGN
832
S: # I did ask the user whether he really wants to sign
833
S: # I did ask the user for the passphrase
834
S: INQUIRE HASHVAL
835
C: D ABCDEF012345678901234
836
C: END
837
S: # signature follows
838
S: D (sig-val rsa (s 45435453654612121212))
839
S: OK
840
841
842
File: gnupg.info, Node: Agent GENKEY, Next: Agent IMPORT, Prev: Agent PKSIGN, Up: Agent Protocol
843
844
2.6.3 Generating a Key
845
----------------------
846
847
This is used to create a new keypair and store the secret key inside the
848
active PSE -- which is in most cases a Soft-PSE. An not yet defined
849
option allows to choose the storage location. To get the secret key out
850
of the PSE, a special export tool has to be used.
851
852
GENKEY
853
854
Invokes the key generation process and the server will then inquire
855
on the generation parameters, like:
856
857
S: INQUIRE KEYPARM
858
C: D (genkey (rsa (nbits 1024)))
859
C: END
860
861
The format of the key parameters which depends on the algorithm is of
862
the form:
863
864
(genkey
865
(algo
866
(parameter_name_1 ....)
867
....
868
(parameter_name_n ....)))
869
870
If everything succeeds, the server returns the *public key* in a SPKI
871
like S-Expression like this:
872
873
(public-key
874
(rsa
875
(n <mpi>)
876
(e <mpi>)))
877
878
Here is an example session:
879
880
C: GENKEY
881
S: INQUIRE KEYPARM
882
C: D (genkey (rsa (nbits 1024)))
883
C: END
884
S: D (public-key
885
S: D (rsa (n 326487324683264) (e 10001)))
886
S OK key created
887
888
889
File: gnupg.info, Node: Agent IMPORT, Next: Agent EXPORT, Prev: Agent GENKEY, Up: Agent Protocol
890
891
2.6.4 Importing a Secret Key
892
----------------------------
893
894
This operation is not yet supportted by GpgAgent. Specialized tools
895
are to be used for this.
896
897
There is no actual need because we can expect that secret keys
898
created by a 3rd party are stored on a smartcard. If we have generated
899
the key ourself, we do not need to import it.
900
901
902
File: gnupg.info, Node: Agent EXPORT, Next: Agent ISTRUSTED, Prev: Agent IMPORT, Up: Agent Protocol
903
904
2.6.5 Export a Secret Key
905
-------------------------
906
907
Not implemented.
908
909
Should be done by an extra tool.
910
911
912
File: gnupg.info, Node: Agent ISTRUSTED, Next: Agent GET_PASSPHRASE, Prev: Agent EXPORT, Up: Agent Protocol
913
914
2.6.6 Importing a Root Certificate
915
----------------------------------
916
917
Actually we do not import a Root Cert but provide a way to validate any
918
piece of data by storing its Hash along with a description and an
919
identifier in the PSE. Here is the interface desription:
920
921
ISTRUSTED <fingerprint>
922
923
Check whether the OpenPGP primary key or the X.509 certificate with
924
the given fingerprint is an ultimately trusted key or a trusted Root CA
925
certificate. The fingerprint should be given as a hexstring (without
926
any blanks or colons or whatever in between) and may be left padded with
927
00 in case of an MD5 fingerprint. GPGAgent will answer with:
928
929
OK
930
931
The key is in the table of trusted keys.
932
933
ERR 304 (Not Trusted)
934
935
The key is not in this table.
936
937
Gpg needs the entire list of trusted keys to maintain the web of
938
trust; the following command is therefore quite helpful:
939
940
LISTTRUSTED
941
942
GpgAgent returns a list of trusted keys line by line:
943
944
S: D 000000001234454556565656677878AF2F1ECCFF P
945
S: D 340387563485634856435645634856438576457A P
946
S: D FEDC6532453745367FD83474357495743757435D S
947
S: OK
948
949
The first item on a line is the hexified fingerprint where MD5
950
ingerprints are `00' padded to the left and the second item is a flag
951
to indicate the type of key (so that gpg is able to only take care of
952
PGP keys). P = OpenPGP, S = S/MIME. A client should ignore the rest
953
of the line, so that we can extend the format in the future.
954
955
Finally a client should be able to mark a key as trusted:
956
957
MARKTRUSTED FINGERPRINT "P"|"S"
958
959
The server will then pop up a window to ask the user whether she
960
really trusts this key. For this it will probably ask for a text to be
961
displayed like this:
962
963
S: INQUIRE TRUSTDESC
964
C: D Do you trust the key with the fingerprint @FPR@
965
C: D bla fasel blurb.
966
C: END
967
S: OK
968
969
Known sequences with the pattern @foo@ are replaced according to this
970
table:
971
972
`@FPR16@'
973
Format the fingerprint according to gpg rules for a v3 keys.
974
975
`@FPR20@'
976
Format the fingerprint according to gpg rules for a v4 keys.
977
978
`@FPR@'
979
Choose an appropriate format to format the fingerprint.
980
981
`@@'
982
Replaced by a single `@'
983
984
985
File: gnupg.info, Node: Agent GET_PASSPHRASE, Next: Agent GET_CONFIRMATION, Prev: Agent ISTRUSTED, Up: Agent Protocol
986
987
2.6.7 Ask for a passphrase
988
--------------------------
989
990
This function is usually used to ask for a passphrase to be used for
991
conventional encryption, but may also be used by programs which need
992
special handling of passphrases. This command uses a syntax which helps
993
clients to use the agent with minimum effort.
994
995
GET_PASSPHRASE [--data] [--check] CACHE_ID [ERROR_MESSAGE PROMPT DESCRIPTION]
996
997
CACHE_ID is expected to be a string used to identify a cached
998
passphrase. Use a `X' to bypass the cache. With no other arguments
999
the agent returns a cached passphrase or an error. By convention
1000
either the hexified fingerprint of the key shall be used for CACHE_ID
1001
or an arbitrary string prefixed with the name of the calling
1002
application and a colon: Like `gpg:somestring'.
1003
1004
ERROR_MESSAGE is either a single `X' for no error message or a
1005
string to be shown as an error message like (e.g. "invalid
1006
passphrase"). Blanks must be percent escaped or replaced by `+''.
1007
1008
PROMPT is either a single `X' for a default prompt or the text to be
1009
shown as the prompt. Blanks must be percent escaped or replaced by `+'.
1010
1011
DESCRIPTION is a text shown above the entry field. Blanks must be
1012
percent escaped or replaced by `+'.
1013
1014
The agent either returns with an error or with a OK followed by the
1015
hex encoded passphrase. Note that the length of the strings is
1016
implicitly limited by the maximum length of a command. If the option
1017
`--data' is used, the passphrase is not returned on the OK line but by
1018
regular data lines; this is the preferred method.
1019
1020
If the option `--check' is used, the standard passphrase constraints
1021
checks are applied. A check is not done if the passphrase has been
1022
found in the cache.
1023
1024
CLEAR_PASSPHRASE CACHE_ID
1025
1026
may be used to invalidate the cache entry for a passphrase. The
1027
function returns with OK even when there is no cached passphrase.
1028
1029
1030
File: gnupg.info, Node: Agent GET_CONFIRMATION, Next: Agent HAVEKEY, Prev: Agent GET_PASSPHRASE, Up: Agent Protocol
1031
1032
2.6.8 Ask for confirmation
1033
--------------------------
1034
1035
This command may be used to ask for a simple confirmation by presenting
1036
a text and 2 bottonts: Okay and Cancel.
1037
1038
GET_CONFIRMATION DESCRIPTION
1039
1040
DESCRIPTIONis displayed along with a Okay and Cancel button. Blanks
1041
must be percent escaped or replaced by `+'. A `X' may be used to
1042
display confirmation dialog with a default text.
1043
1044
The agent either returns with an error or with a OK. Note, that the
1045
length of DESCRIPTION is implicitly limited by the maximum length of a
1046
command.
1047
1048
1049
File: gnupg.info, Node: Agent HAVEKEY, Next: Agent LEARN, Prev: Agent GET_CONFIRMATION, Up: Agent Protocol
1050
1051
2.6.9 Check whether a key is available
1052
--------------------------------------
1053
1054
This can be used to see whether a secret key is available. It does not
1055
return any information on whether the key is somehow protected.
1056
1057
HAVEKEY KEYGRIP
1058
1059
The Agent answers either with OK or `No_Secret_Key' (208). The
1060
caller may want to check for other error codes as well.
1061
1062
1063
File: gnupg.info, Node: Agent LEARN, Next: Agent PASSWD, Prev: Agent HAVEKEY, Up: Agent Protocol
1064
1065
2.6.10 Register a smartcard
1066
---------------------------
1067
1068
LEARN [--send]
1069
1070
This command is used to register a smartcard. With the -send option
1071
given the certificates are send back.
1072
1073
1074
File: gnupg.info, Node: Agent PASSWD, Next: Agent UPDATESTARTUPTTY, Prev: Agent LEARN, Up: Agent Protocol
1075
1076
2.6.11 Change a Passphrase
1077
--------------------------
1078
1079
PASSWD KEYGRIP
1080
1081
This command is used to interactively change the passphrase of the
1082
key indentified by the hex string KEYGRIP.
1083
1084
1085
File: gnupg.info, Node: Agent UPDATESTARTUPTTY, Next: Agent GETEVENTCOUNTER, Prev: Agent PASSWD, Up: Agent Protocol
1086
1087
2.6.12 Change the standard display
1088
----------------------------------
1089
1090
UPDATESTARTUPTTY
1091
1092
Set the startup TTY and X-DISPLAY variables to the values of this
1093
session. This command is useful to direct future pinentry invocations
1094
to another screen. It is only required because there is no way in the
1095
ssh-agent protocol to convey this information.
1096
1097
1098
File: gnupg.info, Node: Agent GETEVENTCOUNTER, Next: Agent GETINFO, Prev: Agent UPDATESTARTUPTTY, Up: Agent Protocol
1099
1100
2.6.13 Get the Event Counters
1101
-----------------------------
1102
1103
GETEVENTCOUNTER
1104
1105
This function return one status line with the current values of the
1106
event counters. The event counters are useful to avoid polling by
1107
delaying a poll until something has changed. The values are decimal
1108
numbers in the range `0' to `UINT_MAX' and wrapping around to 0. The
1109
actual values should not be relied upon; they shall only be used to
1110
detect a change.
1111
1112
The currently defined counters are are:
1113
`ANY'
1114
Incremented with any change of any of the other counters.
1115
1116
`KEY'
1117
Incremented for added or removed private keys.
1118
1119
`CARD'
1120
Incremented for changes of the card readers stati.
1121
1122
1123
File: gnupg.info, Node: Agent GETINFO, Prev: Agent GETEVENTCOUNTER, Up: Agent Protocol
1124
1125
2.6.14 Return information about the process
1126
-------------------------------------------
1127
1128
This is a multipurpose function to return a variety of information.
1129
1130
GETINFO WHAT
1131
1132
The value of WHAT specifies the kind of information returned:
1133
`version'
1134
Return the version of the program.
1135
1136
`pid'
1137
Return the process id of the process.
1138
1139
`socket_name'
1140
Return the name of the socket used to connect the agent.
1141
1142
`ssh_socket_name'
1143
Return the name of the socket used for SSH connections. If SSH
1144
support has not been enabled the error `GPG_ERR_NO_DATA' will be
1145
returned.
1146
1147
1148
File: gnupg.info, Node: Invoking GPG, Next: Invoking GPGSM, Prev: Invoking GPG-AGENT, Up: Top
1149
1150
3 Invoking GPG
1151
**************
1152
1153
`gpg2' is the OpenPGP part of the GNU Privacy Guard (GnuPG). It is a
1154
tool to provide digital encryption and signing services using the
1155
OpenPGP standard. `gpg2' features complete key management and all bells
1156
and whistles you can expect from a decent OpenPGP implementation.
1157
1158
In contrast to the standalone version `gpg', which is more suited
1159
for server and embedded platforms, this version is installed under the
1160
name `gpg2' and more targeted to the desktop as it requires several
1161
other modules to be installed. The standalone version will be kept
1162
maintained and it is possible to install both versions on the same
1163
system. If you need to use different configuration files, you should
1164
make use of something like `gpg.conf-2' instead of just `gpg.conf'.
1165
1166
Documentation for the old standard `gpg' is available as a man page
1167
and at *note GnuPG 1: (gpg)Top.
1168
1169
*Note Option Index::, for an index to `gpg2''s commands and options.
1170
1171
* Menu:
1172
1173
* GPG Commands:: List of all commands.
1174
* GPG Options:: List of all options.
1175
* GPG Configuration:: Configuration files.
1176
* GPG Examples:: Some usage examples.
1177
1178
Developer information:
1179
1180
1181
File: gnupg.info, Node: GPG Commands, Next: GPG Options, Up: Invoking GPG
1182
1183
3.1 Commands
1184
============
1185
1186
Commands are not distinguished from options except for the fact that
1187
only one command is allowed.
1188
1189
`gpg2' may be run with no commands, in which case it will perform a
1190
reasonable action depending on the type of file it is given as input
1191
(an encrypted message is decrypted, a signature is verified, a file
1192
containing keys is listed).
1193
1194
Please remember that option as well as command parsing stops as soon
1195
as a non-option is encountered, you can explicitly stop parsing by
1196
using the special option `--'.
1197
1198
* Menu:
1199
1200
* General GPG Commands:: Commands not specific to the functionality.
1201
* Operational GPG Commands:: Commands to select the type of operation.
1202
* OpenPGP Key Management:: How to manage your keys.
1203
1204
1205
File: gnupg.info, Node: General GPG Commands, Next: Operational GPG Commands, Up: GPG Commands
1206
1207
3.1.1 Commands not specific to the function
1208
-------------------------------------------
1209
1210
`--version'
1211
Print the program version and licensing information. Note that you
1212
cannot abbreviate this command.
1213
1214
`--help'
1215
`-h'
1216
Print a usage message summarizing the most useful command line
1217
options. Not that you cannot abbreviate this command.
1218
1219
`--warranty'
1220
Print warranty information.
1221
1222
`--dump-options'
1223
Print a list of all available options and commands. Note that you
1224
cannot abbreviate this command.
1225
1226
1227
File: gnupg.info, Node: Operational GPG Commands, Next: OpenPGP Key Management, Prev: General GPG Commands, Up: GPG Commands
1228
1229
3.1.2 Commands to select the type of operation
1230
----------------------------------------------
1231
1232
`--sign'
1233
`-s'
1234
Make a signature. This command may be combined with `--encrypt'
1235
(for a signed and encrypted message), `--symmetric' (for a signed
1236
and symmetrically encrypted message), or `--encrypt' and
1237
`--symmetric' together (for a signed message that may be decrypted
1238
via a secret key or a passphrase).
1239
1240
`--clearsign'
1241
Make a clear text signature. The content in a clear text signature
1242
is readable without any special software. OpenPGP software is only
1243
needed to verify the signature. Clear text signatures may modify
1244
end-of-line whitespace for platform independence and are not
1245
intended to be reversible.
1246
1247
`--detach-sign'
1248
`-b'
1249
Make a detached signature.
1250
1251
`--encrypt'
1252
`-e'
1253
Encrypt data. This option may be combined with `--sign' (for a
1254
signed and encrypted message), `--symmetric' (for a message that
1255
may be decrypted via a secret key or a passphrase), or `--sign'
1256
and `--symmetric' together (for a signed message that may be
1257
decrypted via a secret key or a passphrase).
1258
1259
`--symmetric'
1260
`-c'
1261
Encrypt with a symmetric cipher using a passphrase. The default
1262
symmetric cipher used is CAST5, but may be chosen with the
1263
`--cipher-algo' option. This option may be combined with `--sign'
1264
(for a signed and symmetrically encrypted message), `--encrypt'
1265
(for a message that may be decrypted via a secret key or a
1266
passphrase), or `--sign' and `--encrypt' together (for a signed
1267
message that may be decrypted via a secret key or a passphrase).
1268
1269
`--store'
1270
Store only (make a simple RFC1991 literal data packet).
1271
1272
`--decrypt'
1273
`-d'
1274
Decrypt the file given on the command line (or `stdin' if no file
1275
is specified) and write it to stdout (or the file specified with
1276
`--output'). If the decrypted file is signed, the signature is also
1277
verified. This command differs from the default operation, as it
1278
never writes to the filename which is included in the file and it
1279
rejects files which don't begin with an encrypted message.
1280
1281
`--verify'
1282
Assume that the first argument is a signed file or a detached
1283
signature and verify it without generating any output. With no
1284
arguments, the signature packet is read from stdin. If only a
1285
sigfile is given, it may be a complete signature or a detached
1286
signature, in which case the signed stuff is expected in a file
1287
without the ".sig" or ".asc" extension. With more than 1
1288
argument, the first should be a detached signature and the
1289
remaining files are the signed stuff. To read the signed stuff
1290
from stdin, use `-' as the second filename. For security reasons
1291
a detached signature cannot read the signed material from stdin
1292
without denoting it in the above way.
1293
1294
`--multifile'
1295
This modifies certain other commands to accept multiple files for
1296
processing on the command line or read from stdin with each
1297
filename on a separate line. This allows for many files to be
1298
processed at once. `--multifile' may currently be used along with
1299
`--verify', `--encrypt', and `--decrypt'. Note that `--multifile
1300
--verify' may not be used with detached signatures.
1301
1302
`--verify-files'
1303
Identical to `--multifile --verify'.
1304
1305
`--encrypt-files'
1306
Identical to `--multifile --encrypt'.
1307
1308
`--decrypt-files'
1309
Identical to `--multifile --decrypt'.
1310
1311
`--list-keys'
1312
`-k'
1313
`--list-public-keys'
1314
List all keys from the public keyrings, or just the keys given on
1315
the command line.
1316
1317
Avoid using the output of this command in scripts or other
1318
programs as it is likely to change as GnuPG changes. See
1319
`--with-colons' for a machine-parseable key listing command that
1320
is appropriate for use in scripts and other programs.
1321
1322
`--list-secret-keys'
1323
`-K'
1324
List all keys from the secret keyrings, or just the ones given on
1325
the command line. A `#' after the letters `sec' means that the
1326
secret key is not usable (for example, if it was created via
1327
`--export-secret-subkeys').
1328
1329
`--list-sigs'
1330
Same as `--list-keys', but the signatures are listed too.
1331
1332
For each signature listed, there are several flags in between the
1333
"sig" tag and keyid. These flags give additional information about
1334
each signature. From left to right, they are the numbers 1-3 for
1335
certificate check level (see `--ask-cert-level'), "L" for a local
1336
or non-exportable signature (see `--lsign-key'), "R" for a
1337
nonRevocable signature (see the `--edit-key' command "nrsign"),
1338
"P" for a signature that contains a policy URL (see
1339
`--cert-policy-url'), "N" for a signature that contains a notation
1340
(see `--cert-notation'), "X" for an eXpired signature (see
1341
`--ask-cert-expire'), and the numbers 1-9 or "T" for 10 and above
1342
to indicate trust signature levels (see the `--edit-key' command
1343
"tsign").
1344
1345
`--check-sigs'
1346
Same as `--list-sigs', but the signatures are verified.
1347
1348
The status of the verification is indicated by a flag directly
1349
following the "sig" tag (and thus before the flags described above
1350
for `--list-sigs'). A "!" indicates that the signature has been
1351
successfully verified, a "-" denotes a bad signature and a "%" is
1352
used if an error occured while checking the signature (e.g. a non
1353
supported algorithm).
1354
1355
`--fingerprint'
1356
List all keys (or the specified ones) along with their
1357
fingerprints. This is the same output as `--list-keys' but with
1358
the additional output of a line with the fingerprint. May also be
1359
combined with `--list-sigs' or `--check-sigs'. If this command is
1360
given twice, the fingerprints of all secondary keys are listed too.
1361
1362
`--list-packets'
1363
List only the sequence of packets. This is mainly useful for
1364
debugging.
1365
1366
`--card-edit'
1367
Present a menu to work with a smartcard. The subcommand "help"
1368
provides an overview on available commands. For a detailed
1369
description, please see the Card HOWTO at
1370
http://www.gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
1371
1372
`--card-status'
1373
Show the content of the smart card.
1374
1375
`--change-pin'
1376
Present a menu to allow changing the PIN of a smartcard. This
1377
functionality is also available as the subcommand "passwd" with the
1378
`--card-edit' command.
1379
1380
`--delete-key `name''
1381
Remove key from the public keyring. In batch mode either `--yes' is
1382
required or the key must be specified by fingerprint. This is a
1383
safeguard against accidental deletion of multiple keys.
1384
1385
`--delete-secret-key `name''
1386
Remove key from the secret and public keyring. In batch mode the
1387
key must be specified by fingerprint.
1388
1389
`--delete-secret-and-public-key `name''
1390
Same as `--delete-key', but if a secret key exists, it will be
1391
removed first. In batch mode the key must be specified by
1392
fingerprint.
1393
1394
`--export'
1395
Either export all keys from all keyrings (default keyrings and
1396
those registered via option `--keyring'), or if at least one name
1397
is given, those of the given name. The new keyring is written to
1398
stdout or to the file given with option `--output'. Use together
1399
with `--armor' to mail those keys.
1400
1401
`--send-keys `key IDs''
1402
Similar to `--export' but sends the keys to a keyserver.
1403
Fingerprints may be used instead of key IDs. Option `--keyserver'
1404
must be used to give the name of this keyserver. Don't send your
1405
complete keyring to a keyserver -- select only those keys which
1406
are new or changed by you.
1407
1408
`--export-secret-keys'
1409
`--export-secret-subkeys'
1410
Same as `--export', but exports the secret keys instead. This is
1411
normally not very useful and a security risk. The second form of
1412
the command has the special property to render the secret part of
1413
the primary key useless; this is a GNU extension to OpenPGP and
1414
other implementations can not be expected to successfully import
1415
such a key. See the option `--simple-sk-checksum' if you want to
1416
import such an exported key with an older OpenPGP implementation.
1417
1418
`--import'
1419
`--fast-import'
1420
Import/merge keys. This adds the given keys to the keyring. The
1421
fast version is currently just a synonym.
1422
1423
There are a few other options which control how this command works.
1424
Most notable here is the `--keyserver-options merge-only' option
1425
which does not insert new keys but does only the merging of new
1426
signatures, user-IDs and subkeys.
1427
1428
`--recv-keys `key IDs''
1429
Import the keys with the given key IDs from a keyserver. Option
1430
`--keyserver' must be used to give the name of this keyserver.
1431
1432
`--refresh-keys'
1433
Request updates from a keyserver for keys that already exist on the
1434
local keyring. This is useful for updating a key with the latest
1435
signatures, user IDs, etc. Calling this with no arguments will
1436
refresh the entire keyring. Option `--keyserver' must be used to
1437
give the name of the keyserver for all keys that do not have
1438
preferred keyservers set (see `--keyserver-options
1439
honor-keyserver-url').
1440
1441
`--search-keys `names''
1442
Search the keyserver for the given names. Multiple names given
1443
here will be joined together to create the search string for the
1444
keyserver. Option `--keyserver' must be used to give the name of
1445
this keyserver. Keyservers that support different search methods
1446
allow using the syntax specified in "How to specify a user ID"
1447
below. Note that different keyserver types support different
1448
search methods. Currently only LDAP supports them all.
1449
1450
`--fetch-keys `URIs''
1451
Retrieve keys located at the specified URIs. Note that different
1452
installations of GnuPG may support different protocols (HTTP, FTP,
1453
LDAP, etc.)
1454
1455
`--update-trustdb'
1456
Do trust database maintenance. This command iterates over all keys
1457
and builds the Web of Trust. This is an interactive command
1458
because it may have to ask for the "ownertrust" values for keys.
1459
The user has to give an estimation of how far she trusts the owner
1460
of the displayed key to correctly certify (sign) other keys. GnuPG
1461
only asks for the ownertrust value if it has not yet been assigned
1462
to a key. Using the `--edit-key' menu, the assigned value can be
1463
changed at any time.
1464
1465
`--check-trustdb'
1466
Do trust database maintenance without user interaction. From time
1467
to time the trust database must be updated so that expired keys or
1468
signatures and the resulting changes in the Web of Trust can be
1469
tracked. Normally, GnuPG will calculate when this is required and
1470
do it automatically unless `--no-auto-check-trustdb' is set. This
1471
command can be used to force a trust database check at any time.
1472
The processing is identical to that of `--update-trustdb' but it
1473
skips keys with a not yet defined "ownertrust".
1474
1475
For use with cron jobs, this command can be used together with
1476
`--batch' in which case the trust database check is done only if a
1477
check is needed. To force a run even in batch mode add the option
1478
`--yes'.
1479
1480
`--export-ownertrust'
1481
Send the ownertrust values to stdout. This is useful for backup
1482
purposes as these values are the only ones which can't be
1483
re-created from a corrupted trust DB.
1484
1485
`--import-ownertrust'
1486
Update the trustdb with the ownertrust values stored in `files' (or
1487
stdin if not given); existing values will be overwritten.
1488
1489
`--rebuild-keydb-caches'
1490
When updating from version 1.0.6 to 1.0.7 this command should be
1491
used to create signature caches in the keyring. It might be handy
1492
in other situations too.
1493
1494
`--print-md `algo''
1495
`--print-mds'
1496
Print message digest of algorithm ALGO for all given files or
1497
stdin. With the second form (or a deprecated "*" as algo) digests
1498
for all available algorithms are printed.
1499
1500
`--gen-random `0|1|2''
1501
Emit COUNT random bytes of the given quality level. If count is
1502
not given or zero, an endless sequence of random bytes will be
1503
emitted. PLEASE, don't use this command unless you know what you
1504
are doing; it may remove precious entropy from the system!
1505
1506
`--gen-prime `mode' `bits''
1507
Use the source, Luke :-). The output format is still subject to
1508
change.
1509
1510
`--enarmor'
1511
1512
`--dearmor'
1513
Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
1514
This is a GnuPG extension to OpenPGP and in general not very
1515
useful.
1516
1517
1518
1519
File: gnupg.info, Node: OpenPGP Key Management, Prev: Operational GPG Commands, Up: GPG Commands
1520
1521
3.1.3 How to manage your keys
1522
-----------------------------
1523
1524
This section explains the main commands for key management
1525
1526
`--gen-key'
1527
Generate a new key pair. This command is normally only used
1528
interactively.
1529
1530
There is an experimental feature which allows you to create keys in
1531
batch mode. See the file `doc/DETAILS' in the source distribution
1532
on how to use this.
1533
1534
`--gen-revoke `name''
1535
Generate a revocation certificate for the complete key. To revoke
1536
a subkey or a signature, use the `--edit' command.
1537
1538
`--desig-revoke `name''
1539
Generate a designated revocation certificate for a key. This
1540
allows a user (with the permission of the keyholder) to revoke
1541
someone else's key.
1542
1543
`--edit-key'
1544
Present a menu which enables you to do most of the key management
1545
related tasks. It expects the specification of a key on the
1546
command line.
1547
1548
sign
1549
Make a signature on key of user `name' If the key is not yet
1550
signed by the default user (or the users given with -u), the
1551
program displays the information of the key again, together
1552
with its fingerprint and asks whether it should be signed.
1553
This question is repeated for all users specified with -u.
1554
1555
lsign
1556
Same as "sign" but the signature is marked as non-exportable
1557
and will therefore never be used by others. This may be used
1558
to make keys valid only in the local environment.
1559
1560
nrsign
1561
Same as "sign" but the signature is marked as non-revocable
1562
and can therefore never be revoked.
1563
1564
tsign
1565
Make a trust signature. This is a signature that combines the
1566
notions of certification (like a regular signature), and
1567
trust (like the "trust" command). It is generally only useful
1568
in distinct communities or groups.
1569
1570
Note that "l" (for local / non-exportable), "nr" (for
1571
non-revocable, and "t" (for trust) may be freely mixed and
1572
prefixed to "sign" to create a signature of any type desired.
1573
1574
revsig
1575
Revoke a signature. For every signature which has been
1576
generated by one of the secret keys, GnuPG asks whether a
1577
revocation certificate should be generated.
1578
1579
trust
1580
Change the owner trust value. This updates the trust-db
1581
immediately and no save is required.
1582
1583
disable
1584
enable
1585
Disable or enable an entire key. A disabled key can not
1586
normally be used for encryption.
1587
1588
adduid
1589
Create an alternate user id.
1590
1591
addphoto
1592
Create a photographic user id. This will prompt for a JPEG
1593
file that will be embedded into the user ID. Note that a very
1594
large JPEG will make for a very large key. Also note that
1595
some programs will display your JPEG unchanged (GnuPG), and
1596
some programs will scale it to fit in a dialog box (PGP).
1597
1598
deluid
1599
Delete a user id. Note that it is not possible to retract a
1600
user id, once it has been send to the public (i.e. to a
1601
keyserver). In that case you better use `revuid'.
1602
1603
delsig
1604
Delete a signature. Note that it is not possible to retract a
1605
signature, once it has been send to the public (i.e. to a
1606
keyserver). In that case you better use `revsig'.
1607
1608
revuid
1609
Revoke a user id.
1610
1611
addkey
1612
Add a subkey to this key.
1613
1614
addcardkey
1615
Generate a key on a card and add it to this key.
1616
1617
keytocard
1618
Transfer the selected secret key (or the primary key if no
1619
key has been selected) to a smartcard. The secret key in the
1620
keyring will be replaced by a stub if the key could be stored
1621
successfully on the card and you use the save command later.
1622
Only certain key types may be transferred to the card. A sub
1623
menu allows you to select on what card to store the key. Note
1624
that it is not possible to get that key back from the card -
1625
if the card gets broken your secret key will be lost unless
1626
you have a backup somewhere.
1627
1628
bkuptocard `file'
1629
Restore the given file to a card. This command may be used to
1630
restore a backup key (as generated during card
1631
initialization) to a new card. In almost all cases this will
1632
be the encryption key. You should use this command only with
1633
the corresponding public key and make sure that the file
1634
given as argument is indeed the backup to restore. You should
1635
then select 2 to restore as encryption key. You will first
1636
be asked to enter the passphrase of the backup key and then
1637
for the Admin PIN of the card.
1638
1639
delkey
1640
Remove a subkey (secondart key). Note that it is not possible
1641
to retract a subkey, once it has been send to the public
1642
(i.e. to a keyserver). In that case you better use `revkey'.
1643
1644
addrevoker
1645
Add a designated revoker. This takes one optional argument:
1646
"sensitive". If a designated revoker is marked as sensitive,
1647
it will not be exported by default (see export-options).
1648
1649
revkey
1650
Revoke a subkey.
1651
1652
expire
1653
Change the key expiration time. If a subkey is selected, the
1654
expiration time of this subkey will be changed. With no
1655
selection, the key expiration of the primary key is changed.
1656
1657
passwd
1658
Change the passphrase of the secret key.
1659
1660
primary
1661
Flag the current user id as the primary one, removes the
1662
primary user id flag from all other user ids and sets the
1663
timestamp of all affected self-signatures one second ahead.
1664
Note that setting a photo user ID as primary makes it primary
1665
over other photo user IDs, and setting a regular user ID as
1666
primary makes it primary over other regular user IDs.
1667
1668
uid `n'
1669
Toggle selection of user id with index `n'. Use 0 to
1670
deselect all.
1671
1672
key `n'
1673
Toggle selection of subkey with index `n'. Use 0 to deselect
1674
all.
1675
1676
check
1677
Check all selected user ids.
1678
1679
showphoto
1680
Display the selected photographic user id.
1681
1682
pref
1683
List preferences from the selected user ID. This shows the
1684
actual preferences, without including any implied preferences.
1685
1686
showpref
1687
More verbose preferences listing for the selected user ID.
1688
This shows the preferences in effect by including the implied
1689
preferences of 3DES (cipher), SHA-1 (digest), and
1690
Uncompressed (compression) if they are not already included
1691
in the preference list. In addition, the preferred keyserver
1692
and signature notations (if any) are shown.
1693
1694
setpref `string'
1695
Set the list of user ID preferences to `string' for all (or
1696
just the selected) user IDs. Calling setpref with no
1697
arguments sets the preference list to the default (either
1698
built-in or set via `--default-preference-list'), and calling
1699
setpref with "none" as the argument sets an empty preference
1700
list. Use `gpg2 --version' to get a list of available
1701
algorithms. Note that while you can change the preferences on
1702
an attribute user ID (aka "photo ID"), GnuPG does not select
1703
keys via attribute user IDs so these preferences will not be
1704
used by GnuPG.
1705
1706
keyserver
1707
Set a preferred keyserver for the specified user ID(s). This
1708
allows other users to know where you prefer they get your key
1709
from. See `--keyserver-options honor-keyserver-url' for more
1710
on how this works. Setting a value of "none" removes an
1711
existing preferred keyserver.
1712
1713
notation
1714
Set a name=value notation for the specified user ID(s). See
1715
`--cert-notation' for more on how this works. Setting a value
1716
of "none" removes all notations, setting a notation prefixed
1717
with a minus sign (-) removes that notation, and setting a
1718
notation name (without the =value) prefixed with a minus sign
1719
removes all notations with that name.
1720
1721
toggle
1722
Toggle between public and secret key listing.
1723
1724
clean
1725
Compact (by removing all signatures except the selfsig) any
1726
user ID that is no longer usable (e.g. revoked, or expired).
1727
Then, remove any signatures that are not usable by the trust
1728
calculations. Specifically, this removes any signature that
1729
does not validate, any signature that is superseded by a
1730
later signature, revoked signatures, and signatures issued by
1731
keys that are not present on the keyring.
1732
1733
minimize
1734
Make the key as small as possible. This removes all
1735
signatures from each user ID except for the most recent
1736
self-signature.
1737
1738
cross-certify
1739
Add cross-certification signatures to signing subkeys that
1740
may not currently have them. Cross-certification signatures
1741
protect against a subtle attack against signing subkeys. See
1742
`--require-cross-certification'.
1743
1744
save
1745
Save all changes to the key rings and quit.
1746
1747
quit
1748
Quit the program without updating the key rings.
1749
1750
1751
The listing shows you the key with its secondary keys and all user
1752
ids. Selected keys or user ids are indicated by an asterisk. The
1753
trust value is displayed with the primary key: the first is the
1754
assigned owner trust and the second is the calculated trust value.
1755
Letters are used for the values:
1756
1757
-
1758
No ownertrust assigned / not yet calculated.
1759
1760
e
1761
Trust calculation has failed; probably due to an expired key.
1762
1763
q
1764
Not enough information for calculation.
1765
1766
n
1767
Never trust this key.
1768
1769
m
1770
Marginally trusted.
1771
1772
f
1773
Fully trusted.
1774
1775
u
1776
Ultimately trusted.
1777
1778
`--sign-key `name''
1779
Signs a public key with your secret key. This is a shortcut
1780
version of the subcommand "sign" from `--edit'.
1781
1782
`--lsign-key `name''
1783
Signs a public key with your secret key but marks it as
1784
non-exportable. This is a shortcut version of the subcommand
1785
"lsign" from `--edit-key'.
1786
1787
1788
1789
File: gnupg.info, Node: GPG Options, Next: GPG Configuration, Prev: GPG Commands, Up: Invoking GPG
1790
1791
3.2 Option Summary
1792
==================
1793
1794
`gpg2' comes features a bunch of options to control the exact behaviour
1795
and to change the default configuration.
1796
1797
* Menu:
1798
1799
* GPG Configuration Options:: How to change the configuration.
1800
* GPG Key related Options:: Key related options.
1801
* GPG Input and Output:: Input and Output.
1802
* OpenPGP Options:: OpenPGP protocol specific options.
1803
* GPG Esoteric Options:: Doing things one usually don't want to do.
1804
1805
Long options can be put in an options file (default
1806
"~/.gnupg/gpg.conf"). Short option names will not work - for example,
1807
"armor" is a valid option for the options file, while "a" is not. Do not
1808
write the 2 dashes, but simply the name of the option and any required
1809
arguments. Lines with a hash ('#') as the first non-white-space
1810
character are ignored. Commands may be put in this file too, but that is
1811
not generally useful as the command will execute automatically with
1812
every execution of gpg.
1813
1814
Please remember that option parsing stops as soon as a non-option is
1815
encountered, you can explicitly stop parsing by using the special option
1816
`--'.
1817
1818
1819
File: gnupg.info, Node: GPG Configuration Options, Next: GPG Key related Options, Up: GPG Options
1820
1821
3.2.1 How to change the configuration
1822
-------------------------------------
1823
1824
These options are used to change the configuration and are usually found
1825
in the option file.
1826
1827
`--default-key NAME'
1828
Use NAME as the default key to sign with. If this option is not
1829
used, the default key is the first key found in the secret keyring.
1830
Note that `-u' or `--local-user' overrides this option.
1831
1832
`--default-recipient NAME'
1833
Use NAME as default recipient if option `--recipient' is not used
1834
and don't ask if this is a valid one. NAME must be non-empty.
1835
1836
`--default-recipient-self'
1837
Use the default key as default recipient if option `--recipient'
1838
is not used and don't ask if this is a valid one. The default key
1839
is the first one from the secret keyring or the one set with
1840
`--default-key'.
1841
1842
`--no-default-recipient'
1843
Reset `--default-recipient' and `--default-recipient-self'.
1844
1845
`-v, --verbose'
1846
Give more information during processing. If used twice, the input
1847
data is listed in detail.
1848
1849
`--no-verbose'
1850
Reset verbose level to 0.
1851
1852
`-q, --quiet'
1853
Try to be as quiet as possible.
1854
1855
`--batch'
1856
`--no-batch'
1857
Use batch mode. Never ask, do not allow interactive commands.
1858
`--no-batch' disables this option.
1859
1860
`--no-tty'
1861
Make sure that the TTY (terminal) is never used for any output.
1862
This option is needed in some cases because GnuPG sometimes prints
1863
warnings to the TTY even if `--batch' is used.
1864
1865
`--yes'
1866
Assume "yes" on most questions.
1867
1868
`--no'
1869
Assume "no" on most questions.
1870
1871
`--list-options `parameters''
1872
This is a space or comma delimited string that gives options used
1873
when listing keys and signatures (that is, `--list-keys',
1874
`--list-sigs', `--list-public-keys', `--list-secret-keys', and the
1875
`--edit-key' functions). Options can be prepended with a `no-'
1876
(after the two dashes) to give the opposite meaning. The options
1877
are:
1878
1879
show-photos
1880
Causes `--list-keys', `--list-sigs', `--list-public-keys',
1881
and `--list-secret-keys' to display any photo IDs attached to
1882
the key. Defaults to no. See also `--photo-viewer'.
1883
1884
show-policy-urls
1885
Show policy URLs in the `--list-sigs' or `--check-sigs'
1886
listings. Defaults to no.
1887
1888
show-notations
1889
show-std-notations
1890
show-user-notations
1891
Show all, IETF standard, or user-defined signature notations
1892
in the `--list-sigs' or `--check-sigs' listings. Defaults to
1893
no.
1894
1895
show-keyserver-urls
1896
Show any preferred keyserver URL in the `--list-sigs' or
1897
`--check-sigs' listings. Defaults to no.
1898
1899
show-uid-validity
1900
Display the calculated validity of user IDs during key
1901
listings. Defaults to no.
1902
1903
show-unusable-uids
1904
Show revoked and expired user IDs in key listings. Defaults
1905
to no.
1906
1907
show-unusable-subkeys
1908
Show revoked and expired subkeys in key listings. Defaults to
1909
no.
1910
1911
show-keyring
1912
Display the keyring name at the head of key listings to show
1913
which keyring a given key resides on. Defaults to no.
1914
1915
show-sig-expire
1916
Show signature expiration dates (if any) during `--list-sigs'
1917
or `--check-sigs' listings. Defaults to no.
1918
1919
show-sig-subpackets
1920
Include signature subpackets in the key listing. This option
1921
can take an optional argument list of the subpackets to list.
1922
If no argument is passed, list all subpackets. Defaults to
1923
no. This option is only meaningful when using `--with-colons'
1924
along with `--list-sigs' or `--check-sigs'.
1925
1926
`--verify-options `parameters''
1927
This is a space or comma delimited string that gives options used
1928
when verifying signatures. Options can be prepended with a `no-'
1929
to give the opposite meaning. The options are:
1930
1931
show-photos
1932
Display any photo IDs present on the key that issued the
1933
signature. Defaults to no. See also `--photo-viewer'.
1934
1935
show-policy-urls
1936
Show policy URLs in the signature being verified. Defaults to
1937
no.
1938
1939
show-notations
1940
show-std-notations
1941
show-user-notations
1942
Show all, IETF standard, or user-defined signature notations
1943
in the signature being verified. Defaults to IETF standard.
1944
1945
show-keyserver-urls
1946
Show any preferred keyserver URL in the signature being
1947
verified. Defaults to no.
1948
1949
show-uid-validity
1950
Display the calculated validity of the user IDs on the key
1951
that issued the signature. Defaults to no.
1952
1953
show-unusable-uids
1954
Show revoked and expired user IDs during signature
1955
verification. Defaults to no.
1956
1957
show-primary-uid-only
1958
Show only the primary user ID during signature verification.
1959
That is all the AKA lines as well as photo Ids are not shown
1960
with the signature verification status.
1961
1962
pka-lookups
1963
Enable PKA lookups to verify sender addresses. Note that PKA
1964
is based on DNS, and so enabling this option may disclose
1965
information on when and what signatures are verified or to
1966
whom data is encrypted. This is similar to the "web bug"
1967
described for the auto-key-retrieve feature.
1968
1969
pka-trust-increase
1970
Raise the trust in a signature to full if the signature
1971
passes PKA validation. This option is only meaningful if
1972
pka-lookups is set.
1973
1974
`--enable-dsa2'
1975
`--disable-dsa2'
1976
Enables new-style DSA keys which (unlike the old style) may be
1977
larger than 1024 bit and use hashes other than SHA-1 and
1978
RIPEMD/160. Note that very few programs currently support these
1979
keys and signatures from them.
1980
1981
`--photo-viewer `string''
1982
This is the command line that should be run to view a photo ID.
1983
"%i" will be expanded to a filename containing the photo. "%I"
1984
does the same, except the file will not be deleted once the viewer
1985
exits. Other flags are "%k" for the key ID, "%K" for the long key
1986
ID, "%f" for the key fingerprint, "%t" for the extension of the
1987
image type (e.g. "jpg"), "%T" for the MIME type of the image (e.g.
1988
"image/jpeg"), and "%%" for an actual percent sign. If neither %i
1989
or %I are present, then the photo will be supplied to the viewer
1990
on standard input.
1991
1992
The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
1993
stdin". Note that if your image viewer program is not secure, then
1994
executing it from GnuPG does not make it secure.
1995
1996
`--exec-path `string''
1997
Sets a list of directories to search for photo viewers and
1998
keyserver helpers. If not provided, keyserver helpers use the
1999
compiled-in default directory, and photo viewers use the $PATH
2000
environment variable. Note, that on W32 system this value is
2001
ignored when searching for keyserver helpers.
2002
2003
`--keyring `file''
2004
Add `file' to the current list of keyrings. If `file' begins with
2005
a tilde and a slash, these are replaced by the $HOME directory. If
2006
the filename does not contain a slash, it is assumed to be in the
2007
GnuPG home directory ("~/.gnupg" if `--homedir' or $GNUPGHOME is
2008
not used).
2009
2010
Note that this adds a keyring to the current list. If the intent
2011
is to use the specified keyring alone, use `--keyring' along with
2012
`--no-default-keyring'.
2013
2014
`--secret-keyring `file''
2015
Same as `--keyring' but for the secret keyrings.
2016
2017
`--primary-keyring `file''
2018
Designate `file' as the primary public keyring. This means that
2019
newly imported keys (via `--import' or keyserver `--recv-from')
2020
will go to this keyring.
2021
2022
`--trustdb-name `file''
2023
Use `file' instead of the default trustdb. If `file' begins with a
2024
tilde and a slash, these are replaced by the $HOME directory. If
2025
the filename does not contain a slash, it is assumed to be in the
2026
GnuPG home directory (`~/.gnupg' if `--homedir' or $GNUPGHOME is
2027
not used).
2028
2029
`--homedir DIR'
2030
Set the name of the home directory to DIR. If his option is not
2031
used, the home directory defaults to `~/.gnupg'. It is only
2032
recognized when given on the command line. It also overrides any
2033
home directory stated through the environment variable `GNUPGHOME'
2034
or (on W32 systems) by means on the Registry entry
2035
HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
2036
2037
`--display-charset `name''
2038
Set the name of the native character set. This is used to convert
2039
some informational strings like user IDs to the proper UTF-8
2040
encoding. Note that this has nothing to do with the character set
2041
of data to be encrypted or signed; GnuPG does not recode
2042
user-supplied data. If this option is not used, the default
2043
character set is determined from the current locale. A verbosity
2044
level of 3 shows the chosen set. Valid values for `name' are:
2045
2046
iso-8859-1
2047
This is the Latin 1 set.
2048
2049
iso-8859-2
2050
The Latin 2 set.
2051
2052
iso-8859-15
2053
This is currently an alias for the Latin 1 set.
2054
2055
koi8-r
2056
The usual Russian set (rfc1489).
2057
2058
utf-8
2059
Bypass all translations and assume that the OS uses native
2060
UTF-8 encoding.
2061
2062
`--utf8-strings'
2063
`--no-utf8-strings'
2064
Assume that command line arguments are given as UTF8 strings. The
2065
default (`--no-utf8-strings') is to assume that arguments are
2066
encoded in the character set as specified by `--display-charset'.
2067
These options affect all following arguments. Both options may be
2068
used multiple times.
2069
2070
`--options `file''
2071
Read options from `file' and do not try to read them from the
2072
default options file in the homedir (see `--homedir'). This option
2073
is ignored if used in an options file.
2074
2075
`--no-options'
2076
Shortcut for `--options /dev/null'. This option is detected before
2077
an attempt to open an option file. Using this option will also
2078
prevent the creation of a `~/.gnupg' homedir.
2079
2080
`-z `n''
2081
`--compress-level `n''
2082
`--bzip2-compress-level `n''
2083
Set compression level to `n' for the ZIP and ZLIB compression
2084
algorithms. The default is to use the default compression level of
2085
zlib (normally 6). `--bzip2-compress-level' sets the compression
2086
level for the BZIP2 compression algorithm (defaulting to 6 as
2087
well). This is a different option from `--compress-level' since
2088
BZIP2 uses a significant amount of memory for each additional
2089
compression level. `-z' sets both. A value of 0 for `n' disables
2090
compression.
2091
2092
`--bzip2-decompress-lowmem'
2093
Use a different decompression method for BZIP2 compressed files.
2094
This alternate method uses a bit more than half the memory, but
2095
also runs at half the speed. This is useful under extreme low
2096
memory circumstances when the file was originally compressed at a
2097
high `--bzip2-compress-level'.
2098
2099
`--mangle-dos-filenames'
2100
`--no-mangle-dos-filenames'
2101
Older version of Windows cannot handle filenames with more than one
2102
dot. `--mangle-dos-filenames' causes GnuPG to replace (rather than
2103
add to) the extension of an output filename to avoid this problem.
2104
This option is off by default and has no effect on non-Windows
2105
platforms.
2106
2107
`--ask-cert-level'
2108
`--no-ask-cert-level'
2109
When making a key signature, prompt for a certification level. If
2110
this option is not specified, the certification level used is set
2111
via `--default-cert-level'. See `--default-cert-level' for
2112
information on the specific levels and how they are used.
2113
`--no-ask-cert-level' disables this option. This option defaults
2114
to no.
2115
2116
`--default-cert-level `n''
2117
The default to use for the check level when signing a key.
2118
2119
0 means you make no particular claim as to how carefully you
2120
verified the key.
2121
2122
1 means you believe the key is owned by the person who claims to
2123
own it but you could not, or did not verify the key at all. This is
2124
useful for a "persona" verification, where you sign the key of a
2125
pseudonymous user.
2126
2127
2 means you did casual verification of the key. For example, this
2128
could mean that you verified that the key fingerprint and checked
2129
the user ID on the key against a photo ID.
2130
2131
3 means you did extensive verification of the key. For example,
2132
this could mean that you verified the key fingerprint with the
2133
owner of the key in person, and that you checked, by means of a
2134
hard to forge document with a photo ID (such as a passport) that
2135
the name of the key owner matches the name in the user ID on the
2136
key, and finally that you verified (by exchange of email) that the
2137
email address on the key belongs to the key owner.
2138
2139
Note that the examples given above for levels 2 and 3 are just
2140
that: examples. In the end, it is up to you to decide just what
2141
"casual" and "extensive" mean to you.
2142
2143
This option defaults to 0 (no particular claim).
2144
2145
`--min-cert-level'
2146
When building the trust database, treat any signatures with a
2147
certification level below this as invalid. Defaults to 2, which
2148
disregards level 1 signatures. Note that level 0 "no particular
2149
claim" signatures are always accepted.
2150
2151
`--trusted-key `long key ID''
2152
Assume that the specified key (which must be given as a full 8
2153
byte key ID) is as trustworthy as one of your own secret keys.
2154
This option is useful if you don't want to keep your secret keys
2155
(or one of them) online but still want to be able to check the
2156
validity of a given recipient's or signator's key.
2157
2158
`--trust-model `pgp|classic|direct|always|auto''
2159
Set what trust model GnuPG should follow. The models are:
2160
2161
pgp
2162
This is the Web of Trust combined with trust signatures as
2163
used in PGP 5.x and later. This is the default trust model
2164
when creating a new trust database.
2165
2166
classic
2167
This is the standard Web of Trust as used in PGP 2.x and
2168
earlier.
2169
2170
direct
2171
Key validity is set directly by the user and not calculated
2172
via the Web of Trust.
2173
2174
always
2175
Skip key validation and assume that used keys are always fully
2176
trusted. You generally won't use this unless you are using
2177
some external validation scheme. This option also suppresses
2178
the "[uncertain]" tag printed with signature checks when
2179
there is no evidence that the user ID is bound to the key.
2180
2181
auto
2182
Select the trust model depending on whatever the internal
2183
trust database says. This is the default model if such a
2184
database already exists.
2185
2186
`--auto-key-locate `parameters''
2187
`--no-auto-key-locate'
2188
GnuPG can automatically locate and retrieve keys as needed using
2189
this option. This happens when encrypting to an email address (in
2190
the "user@example.com" form), and there are no user@example.com
2191
keys on the local keyring. This option takes any number of the
2192
following arguments, in the order they are to be tried:
2193
2194
cert
2195
locate a key using DNS CERT, as specified in rfc4398.
2196
2197
pka
2198
locate a key using DNS PKA.
2199
2200
ldap
2201
locate a key using the PGP Universal method of checking
2202
"ldap://keys.(thedomain)".
2203
2204
keyserver
2205
locate a key using whatever keyserver is defined using the
2206
`--keyserver' option.
2207
2208
(keyserver URL)
2209
In addition, a keyserver URL as used in the `--keyserver'
2210
option may be used here to query that particular keyserver.
2211
2212
`--keyid-format `short|0xshort|long|0xlong''
2213
Select how to display key IDs. "short" is the traditional
2214
8-character key ID. "long" is the more accurate (but less
2215
convenient) 16-character key ID. Add an "0x" to either to include
2216
an "0x" at the beginning of the key ID, as in 0x99242560.
2217
2218
`--keyserver `name''
2219
Use `name' as your keyserver. This is the server that
2220
`--recv-keys', `--send-keys', and `--search-keys' will communicate
2221
with to receive keys from, send keys to, and search for keys on.
2222
The format of the `name' is a URI:
2223
`scheme:[//]keyservername[:port]' The scheme is the type of
2224
keyserver: "hkp" for the HTTP (or compatible) keyservers, "ldap"
2225
for the LDAP keyservers, or "mailto" for the Graff email
2226
keyserver. Note that your particular installation of GnuPG may
2227
have other keyserver types available as well. Keyserver schemes
2228
are case-insensitive. After the keyserver name, optional keyserver
2229
configuration options may be provided. These are the same as the
2230
global `--keyserver-options' from below, but apply only to this
2231
particular keyserver.
2232
2233
Most keyservers synchronize with each other, so there is generally
2234
no need to send keys to more than one server. The keyserver
2235
`hkp://subkeys.pgp.net' uses round robin DNS to give a different
2236
keyserver each time you use it.
2237
2238
`--keyserver-options `name=value1 ''
2239
This is a space or comma delimited string that gives options for
2240
the keyserver. Options can be prepended with a `no-' to give the
2241
opposite meaning. Valid import-options or export-options may be
2242
used here as well to apply to importing (`--recv-key') or exporting
2243
(`--send-key') a key from a keyserver. While not all options are
2244
available for all keyserver types, some common options are:
2245
2246
include-revoked
2247
When searching for a key with `--search-keys', include keys
2248
that are marked on the keyserver as revoked. Note that not
2249
all keyservers differentiate between revoked and unrevoked
2250
keys, and for such keyservers this option is meaningless.
2251
Note also that most keyservers do not have cryptographic
2252
verification of key revocations, and so turning this option
2253
off may result in skipping keys that are incorrectly marked
2254
as revoked.
2255
2256
include-disabled
2257
When searching for a key with `--search-keys', include keys
2258
that are marked on the keyserver as disabled. Note that this
2259
option is not used with HKP keyservers.
2260
2261
auto-key-retrieve
2262
This option enables the automatic retrieving of keys from a
2263
keyserver when verifying signatures made by keys that are not
2264
on the local keyring.
2265
2266
Note that this option makes a "web bug" like behavior
2267
possible. Keyserver operators can see which keys you
2268
request, so by sending you a message signed by a brand new
2269
key (which you naturally will not have on your local
2270
keyring), the operator can tell both your IP address and the
2271
time when you verified the signature.
2272
2273
honor-keyserver-url
2274
When using `--refresh-keys', if the key in question has a
2275
preferred keyserver URL, then use that preferred keyserver to
2276
refresh the key from. In addition, if auto-key-retrieve is
2277
set, and the signature being verified has a preferred
2278
keyserver URL, then use that preferred keyserver to fetch the
2279
key from. Defaults to yes.
2280
2281
honor-pka-record
2282
If auto-key-retrieve is set, and the signature being verified
2283
has a PKA record, then use the PKA information to fetch the
2284
key. Defaults to yes.
2285
2286
include-subkeys
2287
When receiving a key, include subkeys as potential targets.
2288
Note that this option is not used with HKP keyservers, as
2289
they do not support retrieving keys by subkey id.
2290
2291
use-temp-files
2292
On most Unix-like platforms, GnuPG communicates with the
2293
keyserver helper program via pipes, which is the most
2294
efficient method. This option forces GnuPG to use temporary
2295
files to communicate. On some platforms (such as Win32 and
2296
RISC OS), this option is always enabled.
2297
2298
keep-temp-files
2299
If using `use-temp-files', do not delete the temp files after
2300
using them. This option is useful to learn the keyserver
2301
communication protocol by reading the temporary files.
2302
2303
verbose
2304
Tell the keyserver helper program to be more verbose. This
2305
option can be repeated multiple times to increase the
2306
verbosity level.
2307
2308
timeout
2309
Tell the keyserver helper program how long (in seconds) to
2310
try and perform a keyserver action before giving up. Note
2311
that performing multiple actions at the same time uses this
2312
timeout value per action. For example, when retrieving
2313
multiple keys via `--recv-keys', the timeout applies
2314
separately to each key retrieval, and not to the
2315
`--recv-keys' command as a whole. Defaults to 30 seconds.
2316
2317
http-proxy=`value'
2318
Set the proxy to use for HTTP and HKP keyservers. This
2319
overrides the "http_proxy" environment variable, if any.
2320
2321
max-cert-size
2322
When retrieving a key via DNS CERT, only accept keys up to
2323
this size. Defaults to 16384 bytes.
2324
2325
`--completes-needed `n''
2326
Number of completely trusted users to introduce a new key signer
2327
(defaults to 1).
2328
2329
`--marginals-needed `n''
2330
Number of marginally trusted users to introduce a new key signer
2331
(defaults to 3)
2332
2333
`--max-cert-depth `n''
2334
Maximum depth of a certification chain (default is 5).
2335
2336
`--simple-sk-checksum'
2337
Secret keys are integrity protected by using a SHA-1 checksum. This
2338
method is part of the upcoming enhanced OpenPGP specification but
2339
GnuPG already uses it as a countermeasure against certain attacks.
2340
Old applications don't understand this new format, so this option
2341
may be used to switch back to the old behaviour. Using this option
2342
bears a security risk. Note that using this option only takes
2343
effect when the secret key is encrypted - the simplest way to make
2344
this happen is to change the passphrase on the key (even changing
2345
it to the same value is acceptable).
2346
2347
`--no-sig-cache'
2348
Do not cache the verification status of key signatures. Caching
2349
gives a much better performance in key listings. However, if you
2350
suspect that your public keyring is not save against write
2351
modifications, you can use this option to disable the caching. It
2352
probably does not make sense to disable it because all kind of
2353
damage can be done if someone else has write access to your public
2354
keyring.
2355
2356
`--no-sig-create-check'
2357
GnuPG normally verifies each signature right after creation to
2358
protect against bugs and hardware malfunctions which could leak
2359
out bits from the secret key. This extra verification needs some
2360
time (about 115% for DSA keys), and so this option can be used to
2361
disable it. However, due to the fact that the signature creation
2362
needs manual interaction, this performance penalty does not matter
2363
in most settings.
2364
2365
`--auto-check-trustdb'
2366
`--no-auto-check-trustdb'
2367
If GnuPG feels that its information about the Web of Trust has to
2368
be updated, it automatically runs the `--check-trustdb' command
2369
internally. This may be a time consuming process.
2370
`--no-auto-check-trustdb' disables this option.
2371
2372
`--use-agent'
2373
`--no-use-agent'
2374
This is dummy option. `gpg2' always requires the agent.
2375
2376
`--gpg-agent-info'
2377
This is dummy option. It has no effect when used with `gpg2'.
2378
2379
`--lock-once'
2380
Lock the databases the first time a lock is requested and do not
2381
release the lock until the process terminates.
2382
2383
`--lock-multiple'
2384
Release the locks every time a lock is no longer needed. Use this
2385
to override a previous `--lock-once' from a config file.
2386
2387
`--lock-never'
2388
Disable locking entirely. This option should be used only in very
2389
special environments, where it can be assured that only one process
2390
is accessing those files. A bootable floppy with a stand-alone
2391
encryption system will probably use this. Improper usage of this
2392
option may lead to data and key corruption.
2393
2394
`--exit-on-status-write-error'
2395
This option will cause write errors on the status FD to immediately
2396
terminate the process. That should in fact be the default but it
2397
never worked this way and thus we need an option to enable this,
2398
so that the change won't break applications which close their end
2399
of a status fd connected pipe too early. Using this option along
2400
with `--enable-progress-filter' may be used to cleanly cancel long
2401
running gpg operations.
2402
2403
`--limit-card-insert-tries `n''
2404
With `n' greater than 0 the number of prompts asking to insert a
2405
smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
2406
all ask to insert a card if none has been inserted at startup. This
2407
option is useful in the configuration file in case an application
2408
does not know about the smartcard support and waits ad infinitum
2409
for an inserted card.
2410
2411
`--no-random-seed-file'
2412
GnuPG uses a file to store its internal random pool over
2413
invocations. This makes random generation faster; however
2414
sometimes write operations are not desired. This option can be
2415
used to achieve that with the cost of slower random generation.
2416
2417
`--no-greeting'
2418
Suppress the initial copyright message.
2419
2420
`--no-secmem-warning'
2421
Suppress the warning about "using insecure memory".
2422
2423
`--no-permission-warning'
2424
Suppress the warning about unsafe file and home directory
2425
(`--homedir') permissions. Note that the permission checks that
2426
GnuPG performs are not intended to be authoritative, but rather
2427
they simply warn about certain common permission problems. Do not
2428
assume that the lack of a warning means that your system is secure.
2429
2430
Note that the warning for unsafe `--homedir' permissions cannot be
2431
suppressed in the gpg.conf file, as this would allow an attacker to
2432
place an unsafe gpg.conf file in place, and use this file to
2433
suppress warnings about itself. The `--homedir' permissions
2434
warning may only be suppressed on the command line.
2435
2436
`--no-mdc-warning'
2437
Suppress the warning about missing MDC integrity protection.
2438
2439
`--require-secmem'
2440
`--no-require-secmem'
2441
Refuse to run if GnuPG cannot get secure memory. Defaults to no
2442
(i.e. run, but give a warning).
2443
2444
`--require-cross-certification'
2445
`--no-require-cross-certification'
2446
When verifying a signature made from a subkey, ensure that the
2447
cross certification "back signature" on the subkey is present and
2448
valid. This protects against a subtle attack against subkeys that
2449
can sign. Defaults to `--require-cross-certification' for `gpg2'.
2450
2451
`--expert'
2452
`--no-expert'
2453
Allow the user to do certain nonsensical or "silly" things like
2454
signing an expired or revoked key, or certain potentially
2455
incompatible things like generating unusual key types. This also
2456
disables certain warning messages about potentially incompatible
2457
actions. As the name implies, this option is for experts only. If
2458
you don't fully understand the implications of what it allows you
2459
to do, leave this off. `--no-expert' disables this option.
2460
2461
2462
2463
File: gnupg.info, Node: GPG Key related Options, Next: GPG Input and Output, Prev: GPG Configuration Options, Up: GPG Options
2464
2465
3.2.2 Key related options
2466
-------------------------
2467
2468
`--recipient NAME'
2469
`-r'
2470
Encrypt for user id NAME. If this option or `--hidden-recipient'
2471
is not specified, GnuPG asks for the user-id unless
2472
`--default-recipient' is given.
2473
2474
`--hidden-recipient NAME'
2475
`-R'
2476
Encrypt for user ID NAME, but hide the key ID of this user's key.
2477
This option helps to hide the receiver of the message and is a
2478
limited countermeasure against traffic analysis. If this option or
2479
`--recipient' is not specified, GnuPG asks for the user ID unless
2480
`--default-recipient' is given.
2481
2482
`--encrypt-to `name''
2483
Same as `--recipient' but this one is intended for use in the
2484
options file and may be used with your own user-id as an
2485
"encrypt-to-self". These keys are only used when there are other
2486
recipients given either by use of `--recipient' or by the asked
2487
user id. No trust checking is performed for these user ids and
2488
even disabled keys can be used.
2489
2490
`--hidden-encrypt-to `name''
2491
Same as `--hidden-recipient' but this one is intended for use in
2492
the options file and may be used with your own user-id as a hidden
2493
"encrypt-to-self". These keys are only used when there are other
2494
recipients given either by use of `--recipient' or by the asked
2495
user id. No trust checking is performed for these user ids and
2496
even disabled keys can be used.
2497
2498
`--no-encrypt-to'
2499
Disable the use of all `--encrypt-to' and `--hidden-encrypt-to'
2500
keys.
2501
2502
`--group `name=value1 ''
2503
Sets up a named group, which is similar to aliases in email
2504
programs. Any time the group name is a recipient (`-r' or
2505
`--recipient'), it will be expanded to the values specified.
2506
Multiple groups with the same name are automatically merged into a
2507
single group.
2508
2509
The values are `key IDs' or fingerprints, but any key description
2510
is accepted. Note that a value with spaces in it will be treated as
2511
two different values. Note also there is only one level of
2512
expansion -- you cannot make an group that points to another
2513
group. When used from the command line, it may be necessary to
2514
quote the argument to this option to prevent the shell from
2515
treating it as multiple arguments.
2516
2517
`--ungroup `name''
2518
Remove a given entry from the `--group' list.
2519
2520
`--no-groups'
2521
Remove all entries from the `--group' list.
2522
2523
`--local-user NAME'
2524
`-u'
2525
Use NAME as the key to sign with. Note that this option overrides
2526
`--default-key'.
2527
2528
`--try-all-secrets'
2529
Don't look at the key ID as stored in the message but try all
2530
secret keys in turn to find the right decryption key. This option
2531
forces the behaviour as used by anonymous recipients (created by
2532
using `--throw-keyids') and might come handy in case where an
2533
encrypted message contains a bogus key ID.
2534
2535
2536
2537
File: gnupg.info, Node: GPG Input and Output, Next: OpenPGP Options, Prev: GPG Key related Options, Up: GPG Options
2538
2539
3.2.3 Input and Output
2540
----------------------
2541
2542
`--armor'
2543
`-a'
2544
Create ASCII armored output. The default is to create the binary
2545
OpenPGP format.
2546
2547
`--no-armor'
2548
Assume the input data is not in ASCII armored format.
2549
2550
`--output FILE'
2551
`-o FILE'
2552
Write output to FILE.
2553
2554
`--max-output `n''
2555
This option sets a limit on the number of bytes that will be
2556
generated when processing a file. Since OpenPGP supports various
2557
levels of compression, it is possible that the plaintext of a
2558
given message may be significantly larger than the original
2559
OpenPGP message. While GnuPG works properly with such messages,
2560
there is often a desire to set a maximum file size that will be
2561
generated before processing is forced to stop by the OS limits.
2562
Defaults to 0, which means "no limit".
2563
2564
`--import-options `parameters''
2565
This is a space or comma delimited string that gives options for
2566
importing keys. Options can be prepended with a `no-' to give the
2567
opposite meaning. The options are:
2568
2569
import-local-sigs
2570
Allow importing key signatures marked as "local". This is not
2571
generally useful unless a shared keyring scheme is being used.
2572
Defaults to no.
2573
2574
repair-pks-subkey-bug
2575
During import, attempt to repair the damage caused by the PKS
2576
keyserver bug (pre version 0.9.6) that mangles keys with
2577
multiple subkeys. Note that this cannot completely repair the
2578
damaged key as some crucial data is removed by the keyserver,
2579
but it does at least give you back one subkey. Defaults to no
2580
for regular `--import' and to yes for keyserver `--recv-keys'.
2581
2582
merge-only
2583
During import, allow key updates to existing keys, but do not
2584
allow any new keys to be imported. Defaults to no.
2585
2586
import-clean
2587
After import, compact (remove all signatures except the
2588
self-signature) any user IDs from the new key that are not
2589
usable. Then, remove any signatures from the new key that
2590
are not usable. This includes signatures that were issued by
2591
keys that are not present on the keyring. This option is the
2592
same as running the `--edit-key' command "clean" after
2593
import. Defaults to no.
2594
2595
import-minimal
2596
Import the smallest key possible. This removes all signatures
2597
except the most recent self-signature on each user ID. This
2598
option is the same as running the `--edit-key' command
2599
"minimize" after import. Defaults to no.
2600
2601
`--export-options `parameters''
2602
This is a space or comma delimited string that gives options for
2603
exporting keys. Options can be prepended with a `no-' to give the
2604
opposite meaning. The options are:
2605
2606
export-local-sigs
2607
Allow exporting key signatures marked as "local". This is not
2608
generally useful unless a shared keyring scheme is being used.
2609
Defaults to no.
2610
2611
export-attributes
2612
Include attribute user IDs (photo IDs) while exporting. This
2613
is useful to export keys if they are going to be used by an
2614
OpenPGP program that does not accept attribute user IDs.
2615
Defaults to yes.
2616
2617
export-sensitive-revkeys
2618
Include designated revoker information that was marked as
2619
"sensitive". Defaults to no.
2620
2621
export-reset-subkey-passwd
2622
When using the `--export-secret-subkeys' command, this option
2623
resets the passphrases for all exported subkeys to empty.
2624
This is useful when the exported subkey is to be used on an
2625
unattended machine where a passphrase doesn't necessarily
2626
make sense. Defaults to no.
2627
2628
export-clean
2629
Compact (remove all signatures from) user IDs on the key being
2630
exported if the user IDs are not usable. Also, do not export
2631
any signatures that are not usable. This includes signatures
2632
that were issued by keys that are not present on the keyring.
2633
This option is the same as running the `--edit-key' command
2634
"clean" before export except that the local copy of the key
2635
is not modified. Defaults to no.
2636
2637
export-minimal
2638
Export the smallest key possible. This removes all signatures
2639
except the most recent self-signature on each user ID. This
2640
option is the same as running the `--edit-key' command
2641
"minimize" before export except that the local copy of the
2642
key is not modified. Defaults to no.
2643
2644
`--with-colons'
2645
Print key listings delimited by colons. Note that the output will
2646
be encoded in UTF-8 regardless of any `--display-charset' setting.
2647
This format is useful when GnuPG is called from scripts and other
2648
programs as it is easily machine parsed. The details of this
2649
format are documented in the file `doc/DETAILS', which is included
2650
in the GnuPG source distribution.
2651
2652
`--fixed-list-mode'
2653
Do not merge primary user ID and primary key in `--with-colon'
2654
listing mode and print all timestamps as seconds since 1970-01-01.
2655
2656
`--with-fingerprint'
2657
Same as the command `--fingerprint' but changes only the format of
2658
the output and may be used together with another command.
2659
2660
2661
2662
File: gnupg.info, Node: OpenPGP Options, Next: GPG Esoteric Options, Prev: GPG Input and Output, Up: GPG Options
2663
2664
3.2.4 OpenPGP protocol specific options.
2665
----------------------------------------
2666
2667
`-t, --textmode'
2668
`--no-textmode'
2669
Treat input files as text and store them in the OpenPGP canonical
2670
text form with standard "CRLF" line endings. This also sets the
2671
necessary flags to inform the recipient that the encrypted or
2672
signed data is text and may need its line endings converted back
2673
to whatever the local system uses. This option is useful when
2674
communicating between two platforms that have different line
2675
ending conventions (UNIX-like to Mac, Mac to Windows, etc).
2676
`--no-textmode' disables this option, and is the default.
2677
2678
`--force-v3-sigs'
2679
`--no-force-v3-sigs'
2680
OpenPGP states that an implementation should generate v4 signatures
2681
but PGP versions 5 through 7 only recognize v4 signatures on key
2682
material. This option forces v3 signatures for signatures on data.
2683
Note that this option implies `--ask-sig-expire',
2684
`--sig-policy-url', `--sig-notation', and `--sig-keyserver-url',
2685
as these features cannot be used with v3 signatures.
2686
`--no-force-v3-sigs' disables this option.
2687
2688
`--force-v4-certs'
2689
`--no-force-v4-certs'
2690
Always use v4 key signatures even on v3 keys. This option also
2691
changes the default hash algorithm for v3 RSA keys from MD5 to
2692
SHA-1. `--no-force-v4-certs' disables this option.
2693
2694
`--force-mdc'
2695
Force the use of encryption with a modification detection code.
2696
This is always used with the newer ciphers (those with a blocksize
2697
greater than 64 bits), or if all of the recipient keys indicate
2698
MDC support in their feature flags.
2699
2700
`--disable-mdc'
2701
Disable the use of the modification detection code. Note that by
2702
using this option, the encrypted message becomes vulnerable to a
2703
message modification attack.
2704
2705
`--personal-cipher-preferences `string''
2706
Set the list of personal cipher preferences to `string'. Use
2707
`gpg2 --version' to get a list of available algorithms, and use
2708
`none' to set no preference at all. This allows the user to
2709
factor in their own preferred algorithms when algorithms are chosen
2710
via recipient key preferences. The most highly ranked cipher in
2711
this list is also used for the `--symmetric' encryption command.
2712
2713
`--personal-digest-preferences `string''
2714
Set the list of personal digest preferences to `string'. Use
2715
`gpg2 --version' to get a list of available algorithms, and use
2716
`none' to set no preference at all. This allows the user to
2717
factor in their own preferred algorithms when algorithms are chosen
2718
via recipient key preferences. The most highly ranked digest
2719
algorithm in this list is algo used when signing without encryption
2720
(e.g. `--clearsign' or `--sign'). The default value is SHA-1.
2721
2722
`--personal-compress-preferences `string''
2723
Set the list of personal compression preferences to `string'. Use
2724
`gpg2 --version' to get a list of available algorithms, and use
2725
`none' to set no preference at all. This allows the user to
2726
factor in their own preferred algorithms when algorithms are
2727
chosen via recipient key preferences. The most highly ranked
2728
compression algorithm in this list is algo used when there are no
2729
recipient keys to consider (e.g. `--symmetric').
2730
2731
`--s2k-cipher-algo `name''
2732
Use `name' as the cipher algorithm used to protect secret keys.
2733
The default cipher is CAST5. This cipher is also used for
2734
conventional encryption if `--personal-cipher-preferences' and
2735
`--cipher-algo' is not given.
2736
2737
`--s2k-digest-algo `name''
2738
Use `name' as the digest algorithm used to mangle the passphrases.
2739
The default algorithm is SHA-1.
2740
2741
`--s2k-mode `n''
2742
Selects how passphrases are mangled. If `n' is 0 a plain
2743
passphrase (which is not recommended) will be used, a 1 adds a
2744
salt to the passphrase and a 3 (the default) iterates the whole
2745
process a number of times (see -s2k-count). Unless `--rfc1991' is
2746
used, this mode is also used for conventional encryption.
2747
2748
`--s2k-count `n''
2749
Specify how many times the passphrase mangling is repeated. This
2750
value may range between 1024 and 65011712 inclusive, and the
2751
default is 65536. Note that not all values in the 1024-65011712
2752
range are legal and if an illegal value is selected, GnuPG will
2753
round up to the nearest legal value. This option is only
2754
meaningful if `--s2k-mode' is 3.
2755
2756
2757
3.2.5 Compliance options
2758
------------------------
2759
2760
These options control what GnuPG is compliant to. Only one of these
2761
options may be active at a time. Note that the default setting of this
2762
is nearly always the correct one. See the INTEROPERABILITY WITH OTHER
2763
OPENPGP PROGRAMS section below before using one of these options.
2764
2765
`--gnupg'
2766
Use standard GnuPG behavior. This is essentially OpenPGP behavior
2767
(see `--openpgp'), but with some additional workarounds for common
2768
compatibility problems in different versions of PGP. This is the
2769
default option, so it is not generally needed, but it may be
2770
useful to override a different compliance option in the gpg.conf
2771
file.
2772
2773
`--openpgp'
2774
Reset all packet, cipher and digest options to strict OpenPGP
2775
behavior. Use this option to reset all previous options like
2776
`--s2k-*', `--cipher-algo', `--digest-algo' and `--compress-algo'
2777
to OpenPGP compliant values. All PGP workarounds are disabled.
2778
2779
`--rfc4880'
2780
Reset all packet, cipher and digest options to strict RFC-4880
2781
behavior. Note that this is currently the same thing as
2782
`--openpgp'.
2783
2784
`--rfc2440'
2785
Reset all packet, cipher and digest options to strict RFC-2440
2786
behavior.
2787
2788
`--rfc1991'
2789
Try to be more RFC-1991 (PGP 2.x) compliant.
2790
2791
`--pgp2'
2792
Set up all options to be as PGP 2.x compliant as possible, and
2793
warn if an action is taken (e.g. encrypting to a non-RSA key) that
2794
will create a message that PGP 2.x will not be able to handle.
2795
Note that `PGP 2.x' here means `MIT PGP 2.6.2'. There are other
2796
versions of PGP 2.x available, but the MIT release is a good
2797
common baseline.
2798
2799
This option implies `--rfc1991 --disable-mdc --no-force-v4-certs
2800
--no-sk-comment --escape-from-lines --force-v3-sigs --cipher-algo
2801
IDEA --digest-algo MD5 --compress-algo ZIP'. It also disables
2802
`--textmode' when encrypting.
2803
2804
`--pgp6'
2805
Set up all options to be as PGP 6 compliant as possible. This
2806
restricts you to the ciphers IDEA (if the IDEA plugin is
2807
installed), 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160,
2808
and the compression algorithms none and ZIP. This also disables
2809
-throw-keyids, and making signatures with signing subkeys as PGP 6
2810
does not understand signatures made by signing subkeys.
2811
2812
This option implies `--disable-mdc --no-sk-comment
2813
--escape-from-lines --force-v3-sigs'.
2814
2815
`--pgp7'
2816
Set up all options to be as PGP 7 compliant as possible. This is
2817
identical to `--pgp6' except that MDCs are not disabled, and the
2818
list of allowable ciphers is expanded to add AES128, AES192,
2819
AES256, and TWOFISH.
2820
2821
`--pgp8'
2822
Set up all options to be as PGP 8 compliant as possible. PGP 8 is
2823
a lot closer to the OpenPGP standard than previous versions of
2824
PGP, so all this does is disable `--throw-keyids' and set
2825
`--escape-from-lines'. All algorithms are allowed except for the
2826
SHA224, SHA384, and SHA512 digests.
2827
2828
2829
2830
File: gnupg.info, Node: GPG Esoteric Options, Prev: OpenPGP Options, Up: GPG Options
2831
2832
3.2.6 Doing things one usually doesn't want to do.
2833
--------------------------------------------------
2834
2835
`-n'
2836
`--dry-run'
2837
Don't make any changes (this is not completely implemented).
2838
2839
`--list-only'
2840
Changes the behaviour of some commands. This is like `--dry-run'
2841
but different in some cases. The semantic of this command may be
2842
extended in the future. Currently it only skips the actual
2843
decryption pass and therefore enables a fast listing of the
2844
encryption keys.
2845
2846
`-i'
2847
`--interactive'
2848
Prompt before overwriting any files.
2849
2850
`--debug FLAGS'
2851
Set debugging flags. All flags are or-ed and FLAGS may be given in
2852
C syntax (e.g. 0x0042).
2853
2854
`--debug-all'
2855
Set all useful debugging flags.
2856
2857
`--enable-progress-filter'
2858
Enable certain PROGRESS status outputs. This option allows
2859
frontends to display a progress indicator while gpg is processing
2860
larger files. There is a slight performance overhead using it.
2861
2862
`--status-fd `n''
2863
Write special status strings to the file descriptor `n'. See the
2864
file DETAILS in the documentation for a listing of them.
2865
2866
`--status-file `file''
2867
Same as `--status-fd', except the status data is written to file
2868
`file'.
2869
2870
`--logger-fd `n''
2871
Write log output to file descriptor `n' and not to stderr.
2872
2873
`--log-file `file''
2874
`--logger-file `file''
2875
Same as `--logger-fd', except the logger data is written to file
2876
`file'. Note that `--log-file' is only implemented for GnuPG-2.
2877
2878
`--attribute-fd `n''
2879
Write attribute subpackets to the file descriptor `n'. This is most
2880
useful for use with `--status-fd', since the status messages are
2881
needed to separate out the various subpackets from the stream
2882
delivered to the file descriptor.
2883
2884
`--attribute-file `file''
2885
Same as `--attribute-fd', except the attribute data is written to
2886
file `file'.
2887
2888
`--comment `string''
2889
`--no-comments'
2890
Use `string' as a comment string in clear text signatures and ASCII
2891
armored messages or keys (see `--armor'). The default behavior is
2892
not to use a comment string. `--comment' may be repeated multiple
2893
times to get multiple comment strings. `--no-comments' removes all
2894
comments. It is a good idea to keep the length of a single comment
2895
below 60 characters to avoid problems with mail programs wrapping
2896
such lines. Note that comment lines, like all other header lines,
2897
are not protected by the signature.
2898
2899
`--emit-version'
2900
`--no-emit-version'
2901
Force inclusion of the version string in ASCII armored output.
2902
`--no-emit-version' disables this option.
2903
2904
`--sig-notation `name=value''
2905
`--cert-notation `name=value''
2906
`-N, --set-notation `name=value''
2907
Put the name value pair into the signature as notation data.
2908
`name' must consist only of printable characters or spaces, and
2909
must contain a '@' character in the form keyname@domain.example.com
2910
(substituting the appropriate keyname and domain name, of course).
2911
This is to help prevent pollution of the IETF reserved notation
2912
namespace. The `--expert' flag overrides the '@' check. `value'
2913
may be any printable string; it will be encoded in UTF8, so you
2914
should check that your `--display-charset' is set correctly. If
2915
you prefix `name' with an exclamation mark (!), the notation data
2916
will be flagged as critical (rfc2440:5.2.3.15). `--sig-notation'
2917
sets a notation for data signatures. `--cert-notation' sets a
2918
notation for key signatures (certifications). `--set-notation'
2919
sets both.
2920
2921
There are special codes that may be used in notation names. "%k"
2922
will be expanded into the key ID of the key being signed, "%K"
2923
into the long key ID of the key being signed, "%f" into the
2924
fingerprint of the key being signed, "%s" into the key ID of the
2925
key making the signature, "%S" into the long key ID of the key
2926
making the signature, "%g" into the fingerprint of the key making
2927
the signature (which might be a subkey), "%p" into the fingerprint
2928
of the primary key of the key making the signature, "%c" into the
2929
signature count from the OpenPGP smartcard, and "%%" results in a
2930
single "%". %k, %K, and %f are only meaningful when making a key
2931
signature (certification), and %c is only meaningful when using
2932
the OpenPGP smartcard.
2933
2934
`--sig-policy-url `string''
2935
`--cert-policy-url `string''
2936
`--set-policy-url `string''
2937
Use `string' as a Policy URL for signatures (rfc2440:5.2.3.19). If
2938
you prefix it with an exclamation mark (!), the policy URL packet
2939
will be flagged as critical. `--sig-policy-url' sets a policy url
2940
for data signatures. `--cert-policy-url' sets a policy url for key
2941
signatures (certifications). `--set-policy-url' sets both.
2942
2943
The same %-expandos used for notation data are available here as
2944
well.
2945
2946
`--sig-keyserver-url `string''
2947
Use `string' as a preferred keyserver URL for data signatures. If
2948
you prefix it with an exclamation mark (!), the keyserver URL
2949
packet will be flagged as critical.
2950
2951
The same %-expandos used for notation data are available here as
2952
well.
2953
2954
`--set-filename `string''
2955
Use `string' as the filename which is stored inside messages.
2956
This overrides the default, which is to use the actual filename of
2957
the file being encrypted.
2958
2959
`--for-your-eyes-only'
2960
`--no-for-your-eyes-only'
2961
Set the `for your eyes only' flag in the message. This causes
2962
GnuPG to refuse to save the file unless the `--output' option is
2963
given, and PGP to use a "secure viewer" with a claimed
2964
Tempest-resistant font to display the message. This option
2965
overrides `--set-filename'. `--no-for-your-eyes-only' disables
2966
this option.
2967
2968
`--use-embedded-filename'
2969
`--no-use-embedded-filename'
2970
Try to create a file with a name as embedded in the data. This can
2971
be a dangerous option as it allows to overwrite files. Defaults to
2972
no.
2973
2974
`--cipher-algo `name''
2975
Use `name' as cipher algorithm. Running the program with the
2976
command `--version' yields a list of supported algorithms. If this
2977
is not used the cipher algorithm is selected from the preferences
2978
stored with the key. In general, you do not want to use this
2979
option as it allows you to violate the OpenPGP standard.
2980
`--personal-cipher-preferences' is the safe way to accomplish the
2981
same thing.
2982
2983
`--digest-algo `name''
2984
Use `name' as the message digest algorithm. Running the program
2985
with the command `--version' yields a list of supported
2986
algorithms. In general, you do not want to use this option as it
2987
allows you to violate the OpenPGP standard.
2988
`--personal-digest-preferences' is the safe way to accomplish the
2989
same thing.
2990
2991
`--compress-algo `name''
2992
Use compression algorithm `name'. "zlib" is RFC-1950 ZLIB
2993
compression. "zip" is RFC-1951 ZIP compression which is used by
2994
PGP. "bzip2" is a more modern compression scheme that can
2995
compress some things better than zip or zlib, but at the cost of
2996
more memory used during compression and decompression.
2997
"uncompressed" or "none" disables compression. If this option is
2998
not used, the default behavior is to examine the recipient key
2999
preferences to see which algorithms the recipient supports. If all
3000
else fails, ZIP is used for maximum compatibility.
3001
3002
ZLIB may give better compression results than ZIP, as the
3003
compression window size is not limited to 8k. BZIP2 may give even
3004
better compression results than that, but will use a significantly
3005
larger amount of memory while compressing and decompressing. This
3006
may be significant in low memory situations. Note, however, that
3007
PGP (all versions) only supports ZIP compression. Using any
3008
algorithm other than ZIP or "none" will make the message
3009
unreadable with PGP. In general, you do not want to use this
3010
option as it allows you to violate the OpenPGP standard.
3011
`--personal-compress-preferences' is the safe way to accomplish
3012
the same thing.
3013
3014
`--cert-digest-algo `name''
3015
Use `name' as the message digest algorithm used when signing a
3016
key. Running the program with the command `--version' yields a
3017
list of supported algorithms. Be aware that if you choose an
3018
algorithm that GnuPG supports but other OpenPGP implementations do
3019
not, then some users will not be able to use the key signatures
3020
you make, or quite possibly your entire key.
3021
3022
`--disable-cipher-algo `name''
3023
Never allow the use of `name' as cipher algorithm. The given name
3024
will not be checked so that a later loaded algorithm will still
3025
get disabled.
3026
3027
`--disable-pubkey-algo `name''
3028
Never allow the use of `name' as public key algorithm. The given
3029
name will not be checked so that a later loaded algorithm will
3030
still get disabled.
3031
3032
`--throw-keyids'
3033
`--no-throw-keyids'
3034
Do not put the recipient key IDs into encrypted messages. This
3035
helps to hide the receivers of the message and is a limited
3036
countermeasure against traffic analysis. On the receiving side, it
3037
may slow down the decryption process because all available secret
3038
keys must be tried. `--no-throw-keyids' disables this option.
3039
This option is essentially the same as using `--hidden-recipient'
3040
for all recipients.
3041
3042
`--not-dash-escaped'
3043
This option changes the behavior of cleartext signatures so that
3044
they can be used for patch files. You should not send such an
3045
armored file via email because all spaces and line endings are
3046
hashed too. You can not use this option for data which has 5
3047
dashes at the beginning of a line, patch files don't have this. A
3048
special armor header line tells GnuPG about this cleartext
3049
signature option.
3050
3051
`--escape-from-lines'
3052
`--no-escape-from-lines'
3053
Because some mailers change lines starting with "From " to ">From
3054
" it is good to handle such lines in a special way when creating
3055
cleartext signatures to prevent the mail system from breaking the
3056
signature. Note that all other PGP versions do it this way too.
3057
Enabled by default. `--no-escape-from-lines' disables this option.
3058
3059
`--passphrase-repeat `n''
3060
Specify how many times `gpg2' will request a new passphrase be
3061
repeated. This is useful for helping memorize a passphrase.
3062
Defaults to 1 repetition.
3063
3064
`--passphrase-fd `n''
3065
Read the passphrase from file descriptor `n'. Only the first line
3066
will be read from file descriptor `n'. If you use 0 for `n', the
3067
passphrase will be read from stdin. This can only be used if only
3068
one passphrase is supplied. Note that this passphrase is only
3069
used if the option `--batch' has also been given. This is
3070
different from `gpg'.
3071
3072
`--passphrase-file `file''
3073
Read the passphrase from file `file'. Only the first line will be
3074
read from file `file'. This can only be used if only one
3075
passphrase is supplied. Obviously, a passphrase stored in a file is
3076
of questionable security if other users can read this file. Don't
3077
use this option if you can avoid it. Note that this passphrase is
3078
only used if the option `--batch' has also been given. This is
3079
different from `gpg'.
3080
3081
`--passphrase `string''
3082
Use `string' as the passphrase. This can only be used if only one
3083
passphrase is supplied. Obviously, this is of very questionable
3084
security on a multi-user system. Don't use this option if you can
3085
avoid it. Note that this passphrase is only used if the option
3086
`--batch' has also been given. This is different from `gpg'.
3087
3088
`--command-fd `n''
3089
This is a replacement for the deprecated shared-memory IPC mode.
3090
If this option is enabled, user input on questions is not expected
3091
from the TTY but from the given file descriptor. It should be used
3092
together with `--status-fd'. See the file doc/DETAILS in the source
3093
distribution for details on how to use it.
3094
3095
`--command-file `file''
3096
Same as `--command-fd', except the commands are read out of file
3097
`file'
3098
3099
`--allow-non-selfsigned-uid'
3100
`--no-allow-non-selfsigned-uid'
3101
Allow the import and use of keys with user IDs which are not
3102
self-signed. This is not recommended, as a non self-signed user ID
3103
is trivial to forge. `--no-allow-non-selfsigned-uid' disables.
3104
3105
`--allow-freeform-uid'
3106
Disable all checks on the form of the user ID while generating a
3107
new one. This option should only be used in very special
3108
environments as it does not ensure the de-facto standard format of
3109
user IDs.
3110
3111
`--ignore-time-conflict'
3112
GnuPG normally checks that the timestamps associated with keys and
3113
signatures have plausible values. However, sometimes a signature
3114
seems to be older than the key due to clock problems. This option
3115
makes these checks just a warning. See also `--ignore-valid-from'
3116
for timestamp issues on subkeys.
3117
3118
`--ignore-valid-from'
3119
GnuPG normally does not select and use subkeys created in the
3120
future. This option allows the use of such keys and thus exhibits
3121
the pre-1.0.7 behaviour. You should not use this option unless you
3122
there is some clock problem. See also `--ignore-time-conflict' for
3123
timestamp issues with signatures.
3124
3125
`--ignore-crc-error'
3126
The ASCII armor used by OpenPGP is protected by a CRC checksum
3127
against transmission errors. Occasionally the CRC gets mangled
3128
somewhere on the transmission channel but the actual content
3129
(which is protected by the OpenPGP protocol anyway) is still okay.
3130
This option allows GnuPG to ignore CRC errors.
3131
3132
`--ignore-mdc-error'
3133
This option changes a MDC integrity protection failure into a
3134
warning. This can be useful if a message is partially corrupt,
3135
but it is necessary to get as much data as possible out of the
3136
corrupt message. However, be aware that a MDC protection failure
3137
may also mean that the message was tampered with intentionally by
3138
an attacker.
3139
3140
`--no-default-keyring'
3141
Do not add the default keyrings to the list of keyrings. Note that
3142
GnuPG will not operate without any keyrings, so if you use this
3143
option and do not provide alternate keyrings via `--keyring' or
3144
`--secret-keyring', then GnuPG will still use the default public or
3145
secret keyrings.
3146
3147
`--skip-verify'
3148
Skip the signature verification step. This may be used to make the
3149
decryption faster if the signature verification is not needed.
3150
3151
`--with-key-data'
3152
Print key listings delimited by colons (like `--with-colons') and
3153
print the public key data.
3154
3155
`--fast-list-mode'
3156
Changes the output of the list commands to work faster; this is
3157
achieved by leaving some parts empty. Some applications don't need
3158
the user ID and the trust information given in the listings. By
3159
using this options they can get a faster listing. The exact
3160
behaviour of this option may change in future versions. If you
3161
are missing some information, don't use this option.
3162
3163
`--no-literal'
3164
This is not for normal use. Use the source to see for what it
3165
might be useful.
3166
3167
`--set-filesize'
3168
This is not for normal use. Use the source to see for what it
3169
might be useful.
3170
3171
`--show-session-key'
3172
Display the session key used for one message. See
3173
`--override-session-key' for the counterpart of this option.
3174
3175
We think that Key Escrow is a Bad Thing; however the user should
3176
have the freedom to decide whether to go to prison or to reveal
3177
the content of one specific message without compromising all
3178
messages ever encrypted for one secret key. DON'T USE IT UNLESS
3179
YOU ARE REALLY FORCED TO DO SO.
3180
3181
`--override-session-key `string''
3182
Don't use the public key but the session key `string'. The format
3183
of this string is the same as the one printed by
3184
`--show-session-key'. This option is normally not used but comes
3185
handy in case someone forces you to reveal the content of an
3186
encrypted message; using this option you can do this without
3187
handing out the secret key.
3188
3189
`--ask-sig-expire'
3190
`--no-ask-sig-expire'
3191
When making a data signature, prompt for an expiration time. If
3192
this option is not specified, the expiration time set via
3193
`--default-sig-expire' is used. `--no-ask-sig-expire' disables
3194
this option. Note that by default, `--force-v3-sigs' is set which
3195
also disables this option. If you want signature expiration, you
3196
must set `--no-force-v3-sigs' as well as turning
3197
`--ask-sig-expire' on.
3198
3199
`--default-sig-expire'
3200
The default expiration time to use for signature expiration. Valid
3201
values are "0" for no expiration, a number followed by the letter d
3202
(for days), w (for weeks), m (for months), or y (for years) (for
3203
example "2m" for two months, or "5y" for five years), or an
3204
absolute date in the form YYYY-MM-DD. Defaults to "0".
3205
3206
`--ask-cert-expire'
3207
`--no-ask-cert-expire'
3208
When making a key signature, prompt for an expiration time. If this
3209
option is not specified, the expiration time set via
3210
`--default-cert-expire' is used. `--no-ask-cert-expire' disables
3211
this option.
3212
3213
`--default-cert-expire'
3214
The default expiration time to use for key signature expiration.
3215
Valid values are "0" for no expiration, a number followed by the
3216
letter d (for days), w (for weeks), m (for months), or y (for
3217
years) (for example "2m" for two months, or "5y" for five years),
3218
or an absolute date in the form YYYY-MM-DD. Defaults to "0".
3219
3220
`--allow-secret-key-import'
3221
This is an obsolete option and is not used anywhere.
3222
3223
`--allow-multiple-messages'
3224
3225
`--no-allow-multiple-messages'
3226
Allow processing of multiple OpenPGP messages contained in a single
3227
file or stream. Some programs that call GPG are not prepared to
3228
deal with multiple messages being processed together, so this
3229
option defaults to no. Note that versions of GPG prior to 1.4.7
3230
always allowed multiple messages.
3231
3232
`--enable-special-filenames'
3233
This options enables a mode in which filenames of the form `-&n',
3234
where n is a non-negative decimal number, refer to the file
3235
descriptor n and not to a file with that name.
3236
3237
`--no-expensive-trust-checks'
3238
Experimental use only.
3239
3240
`--preserve-permissions'
3241
Don't change the permissions of a secret keyring back to user
3242
read/write only. Use this option only if you really know what you
3243
are doing.
3244
3245
`--default-preference-list `string''
3246
Set the list of default preferences to `string'. This preference
3247
list is used for new keys and becomes the default for "setpref" in
3248
the edit menu.
3249
3250
`--default-keyserver-url `name''
3251
Set the default keyserver URL to `name'. This keyserver will be
3252
used as the keyserver URL when writing a new self-signature on a
3253
key, which includes key generation and changing preferences.
3254
3255
`--list-config'
3256
Display various internal configuration parameters of GnuPG. This
3257
option is intended for external programs that call GnuPG to
3258
perform tasks, and is thus not generally useful. See the file
3259
`doc/DETAILS' in the source distribution for the details of which
3260
configuration items may be listed. `--list-config' is only usable
3261
with `--with-colons' set.
3262
3263
`--gpgconf-list'
3264
This command is similar to `--list-config' but in general only
3265
internally used by the `gpgconf' tool.
3266
3267
`--gpgconf-test'
3268
This is more or less dummy action. However it parses the
3269
configuration file and returns with failure if the configuration
3270
file would prevent `gpg' from startup. Thus it may be used to run
3271
a syntax check on the configuration file.
3272
3273
3274
3.2.7 Deprecated options
3275
------------------------
3276
3277
`--show-photos'
3278
`--no-show-photos'
3279
Causes `--list-keys', `--list-sigs', `--list-public-keys',
3280
`--list-secret-keys', and verifying a signature to also display
3281
the photo ID attached to the key, if any. See also
3282
`--photo-viewer'. These options are deprecated. Use
3283
`--list-options [no-]show-photos' and/or `--verify-options
3284
[no-]show-photos' instead.
3285
3286
`--show-keyring'
3287
Display the keyring name at the head of key listings to show which
3288
keyring a given key resides on. This option is deprecated: use
3289
`--list-options [no-]show-keyring' instead.
3290
3291
`--always-trust'
3292
Identical to `--trust-model always'. This option is deprecated.
3293
3294
`--show-notation'
3295
`--no-show-notation'
3296
Show signature notations in the `--list-sigs' or `--check-sigs'
3297
listings as well as when verifying a signature with a notation in
3298
it. These options are deprecated. Use `--list-options
3299
[no-]show-notation' and/or `--verify-options [no-]show-notation'
3300
instead.
3301
3302
`--show-policy-url'
3303
`--no-show-policy-url'
3304
Show policy URLs in the `--list-sigs' or `--check-sigs' listings
3305
as well as when verifying a signature with a policy URL in it.
3306
These options are deprecated. Use `--list-options
3307
[no-]show-policy-url' and/or `--verify-options
3308
[no-]show-policy-url' instead.
3309
3310
3311
3312
File: gnupg.info, Node: GPG Configuration, Next: GPG Examples, Prev: GPG Options, Up: Invoking GPG
3313
3314
3.3 Configuration files
3315
=======================
3316
3317
There are a few configuration files to control certain aspects of
3318
`gpg2''s operation. Unless noted, they are expected in the current home
3319
directory (*note option --homedir::).
3320
3321
`gpg.conf'
3322
This is the standard configuration file read by `gpg2' on startup.
3323
It may contain any valid long option; the leading two dashes may
3324
not be entered and the option may not be abbreviated. This default
3325
name may be changed on the command line (*note option --options::).
3326
3327
3328
Note that on larger installations, it is useful to put predefined
3329
files into the directory `/etc/skel/.gnupg/' so that newly created users
3330
start up with a working configuration. For existing users the a small
3331
helper script is provided to create these files (*note addgnupghome::).
3332
3333
For internal purposes `gpg2' creates and maintains a few other
3334
files; They all live in in the current home directory (*note option
3335
--homedir::). Only the `gpg2' may modify these files.
3336
3337
`~/.gnupg/secring.gpg'
3338
The secret keyring.
3339
3340
`~/.gnupg/secring.gpg.lock'
3341
and the lock file
3342
3343
`~/.gnupg/pubring.gpg'
3344
The public keyring
3345
3346
`~/.gnupg/pubring.gpg.lock'
3347
and the lock file
3348
3349
`~/.gnupg/trustdb.gpg'
3350
The trust database
3351
3352
`~/.gnupg/trustdb.gpg.lock'
3353
and the lock file
3354
3355
`~/.gnupg/random_seed'
3356
used to preserve the internal random pool
3357
3358
`/usr[/local]/share/gnupg/options.skel'
3359
Skeleton options file
3360
3361
`/usr[/local]/lib/gnupg/'
3362
Default location for extensions
3363
3364
3365
Operation is further controlled by a few environment variables:
3366
3367
HOME
3368
Used to locate the default home directory.
3369
3370
GNUPGHOME
3371
If set directory used instead of "~/.gnupg".
3372
3373
GPG_AGENT_INFO
3374
Used to locate the gpg-agent. The value consists of 3 colon
3375
delimited fields: The first is the path to the Unix Domain Socket,
3376
the second the PID of the gpg-agent and the protocol version which
3377
should be set to 1. When starting the gpg-agent as described in
3378
its documentation, this variable is set to the correct value. The
3379
option `--gpg-agent-info' can be used to override it.
3380
3381
PINENTRY_USER_DATA
3382
This value is passed via gpg-agent to pinentry. It is useful to
3383
convey extra information to a custom pinentry
3384
3385
COLUMNS
3386
LINES
3387
Used to size some displays to the full size of the screen.
3388
3389
LANGUAGE
3390
Apart from its use by GNU, it is used in the W32 version to
3391
override the language selection done through the Registry. If
3392
used and set to a a valid and available language name (LANGID),
3393
the file with the translation is loaded from
3394
`GPGDIR/gnupg.nls/LANGID.mo'. Here GPGDIR is the directory out of
3395
which the gpg binary has been laoded. If it can't be loaded the
3396
Registry is tried and as last resort the native Windows locale
3397
system is used.
3398
3399
3400
3401
File: gnupg.info, Node: GPG Examples, Prev: GPG Configuration, Up: Invoking GPG
3402
3403
3.4 Examples
3404
============
3405
3406
gpg -se -r `Bob' `file'
3407
sign and encrypt for user Bob
3408
3409
gpg -clearsign `file'
3410
make a clear text signature
3411
3412
gpg -sb `file'
3413
make a detached signature
3414
3415
gpg -list-keys `user_ID'
3416
show keys
3417
3418
gpg -fingerprint `user_ID'
3419
show fingerprint
3420
3421
gpg -verify `pgpfile'
3422
gpg -verify `sigfile'
3423
Verify the signature of the file but do not output the data. The
3424
second form is used for detached signatures, where `sigfile' is
3425
the detached signature (either ASCII armored or binary) and are
3426
the signed data; if this is not given, the name of the file
3427
holding the signed data is constructed by cutting off the
3428
extension (".asc" or ".sig") of `sigfile' or by asking the user
3429
for the filename.
3430
3431
RETURN VALUE
3432
************
3433
3434
The program returns 0 if everything was fine, 1 if at least a signature
3435
was bad, and other error codes for fatal errors.
3436
3437
WARNINGS
3438
********
3439
3440
Use a *good* password for your user account and a *good* passphrase to
3441
protect your secret key. This passphrase is the weakest part of the
3442
whole system. Programs to do dictionary attacks on your secret keyring
3443
are very easy to write and so you should protect your "~/.gnupg/"
3444
directory very well.
3445
3446
Keep in mind that, if this program is used over a network (telnet),
3447
it is *very* easy to spy out your passphrase!
3448
3449
If you are going to verify detached signatures, make sure that the
3450
program knows about it; either give both filenames on the command line
3451
or use `-' to specify stdin.
3452
3453
INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
3454
********************************************
3455
3456
GnuPG tries to be a very flexible implementation of the OpenPGP
3457
standard. In particular, GnuPG implements many of the optional parts of
3458
the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
3459
compression algorithms. It is important to be aware that not all
3460
OpenPGP programs implement these optional algorithms and that by
3461
forcing their use via the `--cipher-algo', `--digest-algo',
3462
`--cert-digest-algo', or `--compress-algo' options in GnuPG, it is
3463
possible to create a perfectly valid OpenPGP message, but one that
3464
cannot be read by the intended recipient.
3465
3466
There are dozens of variations of OpenPGP programs available, and
3467
each supports a slightly different subset of these optional algorithms.
3468
For example, until recently, no (unhacked) version of PGP supported the
3469
BLOWFISH cipher algorithm. A message using BLOWFISH simply could not be
3470
read by a PGP user. By default, GnuPG uses the standard OpenPGP
3471
preferences system that will always do the right thing and create
3472
messages that are usable by all recipients, regardless of which OpenPGP
3473
program they use. Only override this safe default if you really know
3474
what you are doing.
3475
3476
If you absolutely must override the safe default, or if the
3477
preferences on a given key are invalid for some reason, you are far
3478
better off using the `--pgp6', `--pgp7', or `--pgp8' options. These
3479
options are safe as they do not force any particular algorithms in
3480
violation of OpenPGP, but rather reduce the available algorithms to a
3481
"PGP-safe" list.
3482
3483
BUGS
3484
****
3485
3486
On many systems this program should be installed as setuid(root). This
3487
is necessary to lock memory pages. Locking memory pages prevents the
3488
operating system from writing memory pages (which may contain
3489
passphrases or other sensitive material) to disk. If you get no warning
3490
message about insecure memory your operating system supports locking
3491
without being root. The program drops root privileges as soon as locked
3492
memory is allocated.
3493
3494
Note also that some systems (especially laptops) have the ability to
3495
"suspend to disk" (also known as "safe sleep" or "hibernate"). This
3496
writes all memory to disk before going into a low power or even powered
3497
off mode. Unless measures are taken in the operating system to protect
3498
the saved memory, passphrases or other sensitive material may be
3499
recoverable from it later.
3500
3501
3502
File: gnupg.info, Node: Invoking GPGSM, Next: Invoking SCDAEMON, Prev: Invoking GPG, Up: Top
3503
3504
4 Invoking GPGSM
3505
****************
3506
3507
`gpgsm' is a tool similar to `gpg' to provide digital encryption and
3508
signing servicesd on X.509 certificates and the CMS protocol. It is
3509
mainly used as a backend for S/MIME mail processing. `gpgsm' includes
3510
a full features certificate management and complies with all rules
3511
defined for the German Sphinx project.
3512
3513
*Note Option Index::, for an index to `GPGSM''s commands and options.
3514
3515
* Menu:
3516
3517
* GPGSM Commands:: List of all commands.
3518
* GPGSM Options:: List of all options.
3519
* GPGSM Configuration:: Configuration files.
3520
* GPGSM Examples:: Some usage examples.
3521
3522
Developer information:
3523
* Unattended Usage:: Using `gpgsm' from other programs.
3524
* GPGSM Protocol:: The protocol the server mode uses.
3525
3526
3527
File: gnupg.info, Node: GPGSM Commands, Next: GPGSM Options, Up: Invoking GPGSM
3528
3529
4.1 Commands
3530
============
3531
3532
Commands are not distinguished from options except for the fact that
3533
only one command is allowed.
3534
3535
* Menu:
3536
3537
* General GPGSM Commands:: Commands not specific to the functionality.
3538
* Operational GPGSM Commands:: Commands to select the type of operation.
3539
* Certificate Management:: How to manage certificates.
3540
3541
3542
File: gnupg.info, Node: General GPGSM Commands, Next: Operational GPGSM Commands, Up: GPGSM Commands
3543
3544
4.1.1 Commands not specific to the function
3545
-------------------------------------------
3546
3547
`--version'
3548
Print the program version and licensing information. Not that you
3549
can abbreviate this command.
3550
3551
`--help, -h'
3552
Print a usage message summarizing the most usefule command-line
3553
options. Not that you can abbreviate this command.
3554
3555
`--warranty'
3556
Print warranty information.
3557
3558
`--dump-options'
3559
Print a list of all available options and commands. Not that you
3560
can abbreviate this command.
3561
3562
3563
File: gnupg.info, Node: Operational GPGSM Commands, Next: Certificate Management, Prev: General GPGSM Commands, Up: GPGSM Commands
3564
3565
4.1.2 Commands to select the type of operation
3566
----------------------------------------------
3567
3568
`--encrypt'
3569
Perform an encryption. The keys the data is encrypted too must be
3570
set using the option `--recipient'.
3571
3572
`--decrypt'
3573
Perform a decryption; the type of input is automatically
3574
determined. It may either be in binary form or PEM encoded;
3575
automatic determination of base-64 encoding is not done.
3576
3577
`--sign'
3578
Create a digital signature. The key used is either the fist one
3579
found in the keybox or those set with the `--local-user' option.
3580
3581
`--verify'
3582
Check a signature file for validity. Depending on the arguments a
3583
detached signatrue may also be checked.
3584
3585
`--server'
3586
Run in server mode and wait for commands on the `stdin'.
3587
3588
`--call-dirmngr COMMAND [ARGS]'
3589
Behave as a Dirmngr client issuing the request COMMAND with the
3590
optional list of ARGS. The output of the Dirmngr is printed
3591
stdout. Please note that file names given as arguments should
3592
have an absulte file name (i.e. commencing with `/' because they
3593
are passed verbatim to the Dirmngr and the working directory of the
3594
Dirmngr might not be the same as the one of this client.
3595
Currently it is not possible to pass data via stdin to the
3596
Dirmngr. COMMAND should not contain spaces.
3597
3598
This is command is required for certain maintaining tasks of the
3599
dirmngr where a dirmngr must be able to call back to `gpgsm'. See
3600
the Dirmngr manual for details.
3601
3602
`--call-protect-tool ARGUMENTS'
3603
Certain maintenance operations are done by an external program call
3604
`gpg-protect-tool'; this is usually not installed in a directory
3605
listed in the PATH variable. This command provides a simple
3606
wrapper to access this tool. ARGUMENTS are passed verbatim to
3607
this command; use `--help' to get a list of supported operations.
3608
3609
3610
3611
File: gnupg.info, Node: Certificate Management, Prev: Operational GPGSM Commands, Up: GPGSM Commands
3612
3613
4.1.3 How to manage the certificates and keys
3614
---------------------------------------------
3615
3616
`--gen-key'
3617
This command allows the interactive creation of a certifcate
3618
signing request. It is commonly used along with the `--output'
3619
option to save the created CSR into a file.
3620
3621
`--list-keys'
3622
`-k'
3623
List all available certificates stored in the local key database.
3624
Note that the displayed data might be reformatted for better human
3625
readability and illegal characters are replaced by safe
3626
substitutes.
3627
3628
`--list-secret-keys'
3629
`-K'
3630
List all available certificates for which a corresponding a secret
3631
key is available.
3632
3633
`--list-external-keys PATTERN'
3634
List certificates matching PATTERN using an external server. This
3635
utilizes the `dirmngr' service.
3636
3637
`--list-chain'
3638
Same as `--list-keys' but also prints all keys making up the chain.
3639
3640
`--dump-cert'
3641
`--dump-keys'
3642
List all available certificates stored in the local key database
3643
using a format useful mainly for debugging.
3644
3645
`--dump-chain'
3646
Same as `--dump-keys' but also prints all keys making up the chain.
3647
3648
`--dump-secret-keys'
3649
List all available certificates for which a corresponding a secret
3650
key is available using a format useful mainly for debugging.
3651
3652
`--dump-external-keys PATTERN'
3653
List certificates matching PATTERN using an external server. This
3654
utilizes the `dirmngr' service. It uses a format useful mainly
3655
for debugging.
3656
3657
`--keydb-clear-some-cert-flags'
3658
This is a debugging aid to reset certain flags in the key database
3659
which are used to cache certain certificate stati. It is
3660
especially useful if a bad CRL or a weird running OCSP reponder
3661
did accidently revoke certificate. There is no security issue
3662
with this command because `gpgsm' always make sure that the
3663
validity of a certificate is checked right before it is used.
3664
3665
`--delete-keys PATTERN'
3666
Delete the keys matching PATTERN.
3667
3668
`--export [PATTERN]'
3669
Export all certificates stored in the Keybox or those specified by
3670
the optional PATTERN. Those pattern consist of a list of user ids
3671
(*note how-to-specify-a-user-id::). When used along with the
3672
`--armor' option a few informational lines are prepended before
3673
each block. There is one limitation: As there is no commonly
3674
agreed upon way to pack more than one certificate into an ASN.1
3675
structure, the binary export (i.e. without using `armor') works
3676
only for the export of one certificate. Thus it is required to
3677
specify a PATTERN which yields exactly one certificate.
3678
3679
`--export-secret-key-p12 KEY-ID'
3680
Export the private key and the certificate identified by KEY-ID in
3681
a PKCS#12 format. When using along with the `--armor' option a few
3682
informational lines are prepended to the output. Note, that the
3683
PKCS#12 format is not very secure and this command is only
3684
provided if there is no other way to exchange the private key.
3685
(*note option --p12-charset::)
3686
3687
`--import [FILES]'
3688
Import the certificates from the PEM or binary encoded files as
3689
well as from signed-only messages. This command may also be used
3690
to import a secret key from a PKCS#12 file.
3691
3692
`--learn-card'
3693
Read information about the private keys from the smartcard and
3694
import the certificates from there. This command utilizes the
3695
`gpg-agent' and in turn the `scdaemon'.
3696
3697
`--passwd USER_ID'
3698
Change the passphrase of the private key belonging to the
3699
certificate specified as USER_ID. Note, that changing the
3700
passphrase/PIN of a smartcard is not yet supported.
3701
3702
3703
3704
File: gnupg.info, Node: GPGSM Options, Next: GPGSM Configuration, Prev: GPGSM Commands, Up: Invoking GPGSM
3705
3706
4.2 Option Summary
3707
==================
3708
3709
`GPGSM' comes features a bunch ofoptions to control the exact behaviour
3710
and to change the default configuration.
3711
3712
* Menu:
3713
3714
* Configuration Options:: How to change the configuration.
3715
* Certificate Options:: Certificate related options.
3716
* Input and Output:: Input and Output.
3717
* CMS Options:: How to change how the CMS is created.
3718
* Esoteric Options:: Doing things one usually don't want to do.
3719
3720
3721
File: gnupg.info, Node: Configuration Options, Next: Certificate Options, Up: GPGSM Options
3722
3723
4.2.1 How to change the configuration
3724
-------------------------------------
3725
3726
These options are used to change the configuraton and are usually found
3727
in the option file.
3728
3729
`--options FILE'
3730
Reads configuration from FILE instead of from the default per-user
3731
configuration file. The default configuration file is named
3732
`gpgsm.conf' and expected in the `.gnupg' directory directly below
3733
the home directory of the user.
3734
3735
`--homedir DIR'
3736
Set the name of the home directory to DIR. If his option is not
3737
used, the home directory defaults to `~/.gnupg'. It is only
3738
recognized when given on the command line. It also overrides any
3739
home directory stated through the environment variable `GNUPGHOME'
3740
or (on W32 systems) by means on the Registry entry
3741
HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
3742
3743
`-v'
3744
3745
`--verbose'
3746
Outputs additional information while running. You can increase
3747
the verbosity by giving several verbose commands to `gpgsm', such
3748
as `-vv'.
3749
3750
`--policy-file FILENAME'
3751
Change the default name of the policy file to FILENAME.
3752
3753
`--agent-program FILE'
3754
Specify an agent program to be used for secret key operations. The
3755
default value is the `/usr/local/bin/gpg-agent'. This is only used
3756
as a fallback when the envrionment variable `GPG_AGENT_INFO' is not
3757
set or a running agent can't be connected.
3758
3759
`--dirmngr-program FILE'
3760
Specify a dirmngr program to be used for CRL checks. The default
3761
value is `/usr/sbin/dirmngr'. This is only used as a fallback
3762
when the environment variable `DIRMNGR_INFO' is not set or a
3763
running dirmngr can't be connected.
3764
3765
`--prefer-system-dirmngr'
3766
If a system wide `dirmngr' is running in daemon mode, first try to
3767
connect to this one. Fallback to a pipe based server if this does
3768
not work. Under Windows this option is ignored because the system
3769
dirmngr is always used.
3770
3771
`--disable-dirmngr'
3772
Entirely disable the use of the Dirmngr.
3773
3774
`--no-secmem-warning'
3775
Don't print a warning when the so called "secure memory" can't be
3776
used.
3777
3778
`--log-file FILE'
3779
When running in server mode, append all logging output to FILE.
3780
3781
3782
3783
File: gnupg.info, Node: Certificate Options, Next: Input and Output, Prev: Configuration Options, Up: GPGSM Options
3784
3785
4.2.2 Certificate related options
3786
---------------------------------
3787
3788
`--enable-policy-checks'
3789
`--disable-policy-checks'
3790
By default policy checks are enabled. These options may be used to
3791
change it.
3792
3793
`--enable-crl-checks'
3794
`--disable-crl-checks'
3795
By default the CRL checks are enabled and the DirMngr is used to
3796
check for revoked certificates. The disable option is most useful
3797
with an off-line network connection to suppress this check.
3798
3799
`--enable-trusted-cert-crl-check'
3800
`--disable-trusted-cert-crl-check'
3801
By default the CRL for trusted root certificates are checked like
3802
for any other certificates. This allows a CA to revoke its own
3803
certificates voluntary without the need of putting all ever issued
3804
certificates into a CRL. The disable option may be used to switch
3805
this extra check off. Due to the caching done by the Dirmngr,
3806
there won't be any noticeable performance gain. Note, that this
3807
also disables possible OCSP checks for trusted root certificates.
3808
A more specific way of disabling this check is by adding the
3809
"relax" keyword to the root CA line of the `trustlist.txt'
3810
3811
`--force-crl-refresh'
3812
Tell the dirmngr to reload the CRL for each request. For better
3813
performance, the dirmngr will actually optimize this by suppressing
3814
the loading for short time intervalls (e.g. 30 minutes). This
3815
option is useful to make sure that a fresh CRL is available for
3816
certificates hold in the keybox. The suggested way of doing this
3817
is by using it along with the option `--with-validation' for a key
3818
listing command. This option should not be used in a
3819
configuration file.
3820
3821
`--enable-ocsp'
3822
`--disable-ocsp'
3823
Be default OCSP checks are disabled. The enable option may be
3824
used to enable OCSP checks via Dirmngr. If CRL checks are also
3825
enabled, CRLs will be used as a fallback if for some reason an
3826
OCSP request won't succeed. Note, that you have to allow OCSP
3827
requests in Dirmngr's configuration too (option `--allow-ocsp' and
3828
configure dirmngr properly. If you don't do so you will get the
3829
error code `Not supported'.
3830
3831
`--auto-issuer-key-retrieve'
3832
If a required certificate is missing while validating the chain of
3833
certificates, try to load that certificate from an external
3834
location. This usually means that Dirmngr is employed t search
3835
for the certificate. Note that this option makes a "web bug" like
3836
behavior possible. LDAP server operators can see which keys you
3837
request, so by sending you a message signed by a brand new key
3838
(which you naturally will not have on your local keybox), the
3839
operator can tell both your IP address and the time when you
3840
verified the signature.
3841
3842
`--validation-model NAME'
3843
This option changes the default validation model. The only
3844
possible values are "shell" (which is the default) and "chain"
3845
which forces the use of the chain model. The chain model is also
3846
used if an option in the `trustlist.txt' or an attribute of the
3847
certificate requests it. However the standard model (shell) is in
3848
that case always tried first.
3849
3850
3851
3852
File: gnupg.info, Node: Input and Output, Next: CMS Options, Prev: Certificate Options, Up: GPGSM Options
3853
3854
4.2.3 Input and Output
3855
----------------------
3856
3857
`--armor'
3858
`-a'
3859
Create PEM encoded output. Default is binary output.
3860
3861
`--base64'
3862
Create Base-64 encoded output; i.e. PEM without the header lines.
3863
3864
`--assume-armor'
3865
Assume the input data is PEM encoded. Default is to autodetect the
3866
encoding but this is may fail.
3867
3868
`--assume-base64'
3869
Assume the input data is plain base-64 encoded.
3870
3871
`--assume-binary'
3872
Assume the input data is binary encoded.
3873
3874
`--p12-charset NAME'
3875
`gpgsm' uses the UTF-8 encoding when encoding passphrases for
3876
PKCS#12 files. This option may be used to force the passphrase to
3877
be encoded in the specified encoding NAME. This is useful if the
3878
application used to import the key uses a different encoding and
3879
thus won't be able to import a file generated by `gpgsm'. Commonly
3880
used values for NAME are `Latin1' and `CP850'. Note that `gpgsm'
3881
itself automagically imports any file with a passphrase encoded to
3882
the most commonly used encodings.
3883
3884
`--default-key USER_ID'
3885
Use USER_ID as the standard key for signing. This key is used if
3886
no other key has been defined as a signing key. Note, that the
3887
first `--local-users' option also sets this key if it has not yet
3888
been set; however `--default-key' always overrides this.
3889
3890
`--local-user USER_ID'
3891
3892
`-u USER_ID'
3893
Set the user(s) to be used for signing. The default is the first
3894
secret key found in the database.
3895
3896
`--recipient NAME'
3897
`-r'
3898
Encrypt to the user id NAME. There are several ways a user id may
3899
be given (*note how-to-specify-a-user-id::).
3900
3901
`--output FILE'
3902
`-o FILE'
3903
Write output to FILE. The default is to write it to stdout.
3904
3905
`--with-key-data'
3906
Displays extra information with the `--list-keys' commands.
3907
Especially a line tagged `grp' is printed which tells you the
3908
keygrip of a key. This string is for example used as the file
3909
name of the secret key.
3910
3911
`--with-validation'
3912
When doing a key listing, do a full validation check for each key
3913
and print the result. This is usually a slow operation because it
3914
requires a CRL lookup and other operations.
3915
3916
When used along with -import, a validation of the certificate to
3917
import is done and only imported if it succeeds the test. Note
3918
that this does not affect an already available cwertificate in the
3919
DB. This option is therefore useful to simply verify a
3920
certificate.
3921
3922
`--with-md5-fingerprint'
3923
For standard key listings, also print the MD5 fingerprint of the
3924
certificate.
3925
3926
3927
3928
File: gnupg.info, Node: CMS Options, Next: Esoteric Options, Prev: Input and Output, Up: GPGSM Options
3929
3930
4.2.4 How to change how the CMS is created.
3931
-------------------------------------------
3932
3933
`--include-certs N'
3934
Using N of -2 includes all certificate except for the root cert,
3935
-1 includes all certs, 0 does not include any certs, 1 includes
3936
only the signers cert (this is the default) and all other positive
3937
values include up to N certificates starting with the signer cert.
3938
3939
`--cipher-algo OID'
3940
Use the cipher algorithm with the ASN.1 object identifier OID for
3941
encryption. For convenience the strings `3DES', `AES' and
3942
`AES256' may be used instead of their OIDs. The default is `3DES'
3943
(1.2.840.113549.3.7).
3944
3945
3946
3947
File: gnupg.info, Node: Esoteric Options, Prev: CMS Options, Up: GPGSM Options
3948
3949
4.2.5 Doing things one usually don't want to do.
3950
------------------------------------------------
3951
3952
`--extra-digest-algo NAME'
3953
Sometimes signatures are broken in that they announce a different
3954
digest algorithm than actually used. `gpgsm' uses a one-pass data
3955
processing model and thus needs to rely on the announcde digest
3956
algorithms to properly hash the data. As a workaround this option
3957
may be used to tell gpg to also hash the data using the algorithm
3958
NAME; this slows processing down a little bit but allows to verify
3959
such broken signatures. If `gpgsm' prints an error like "digest
3960
algo 8 has not been enabled" you may want to try this option, with
3961
`SHA256' for NAME.
3962
3963
`--faked-system-time EPOCH'
3964
This option is only useful for testing; it sets the system time
3965
back or forth to EPOCH which is the number of seconds elapsed
3966
since the year 1970. Alternativly EPOCH may be given as a full
3967
ISO time string (e.g. "20070924T154812").
3968
3969
`--with-ephemeral-keys'
3970
Include ephemeral flagged keys in the output of key listings.
3971
3972
`--debug-level LEVEL'
3973
Select the debug level for investigating problems. LEVEL may be
3974
one of:
3975
3976
`none'
3977
no debugging at all.
3978
3979
`basic'
3980
some basic debug messages
3981
3982
`advanced'
3983
more verbose debug messages
3984
3985
`expert'
3986
even more detailed messages
3987
3988
`guru'
3989
all of the debug messages you can get
3990
3991
How these messages are mapped to the actual debugging flags is not
3992
specified and may change with newer releases of this program. They
3993
are however carefully selected to best aid in debugging.
3994
3995
`--debug FLAGS'
3996
This option is only useful for debugging and the behaviour may
3997
change at any time without notice; using `--debug-levels' is the
3998
preferred method to select the debug verbosity. FLAGS are bit
3999
encoded and may be given in usual C-Syntax. The currently defined
4000
bits are:
4001
4002
`0 (1)'
4003
X.509 or OpenPGP protocol related data
4004
4005
`1 (2)'
4006
values of big number integers
4007
4008
`2 (4)'
4009
low level crypto operations
4010
4011
`5 (32)'
4012
memory allocation
4013
4014
`6 (64)'
4015
caching
4016
4017
`7 (128)'
4018
show memory statistics.
4019
4020
`9 (512)'
4021
write hashed data to files named `dbgmd-000*'
4022
4023
`10 (1024)'
4024
trace Assuan protocol
4025
4026
Note, that all flags set using this option may get overriden by
4027
`--debug-level'.
4028
4029
`--debug-all'
4030
Same as `--debug=0xffffffff'
4031
4032
`--debug-allow-core-dump'
4033
Usually `gpgsm' tries to avoid dumping core by well written code
4034
and by disabling core dumps for security reasons. However, bugs
4035
are pretty durable beasts and to squash them it is sometimes
4036
useful to have a core dump. This option enables core dumps unless
4037
the Bad Thing happened before the option parsing.
4038
4039
`--debug-no-chain-validation'
4040
This is actually not a debugging option but only useful as such.
4041
It lets `gpgsm' bypass all certificate chain validation checks.
4042
4043
`--debug-ignore-expiration'
4044
This is actually not a debugging option but only useful as such.
4045
It lets `gpgsm' ignore all notAfter dates, this is used by the
4046
regresssion tests.
4047
4048
`--fixed-passphrase STRING'
4049
Supply the passphrase STRING to the gpg-protect-tool. This option
4050
is only useful for the regression tests included with this package
4051
and may be revised or removed at any time without notice.
4052
4053
`--no-common-certs-import'
4054
Suppress the import of common certificates on keybox creation.
4055
4056
4057
All the long options may also be given in the configuration file
4058
after stripping off the two leading dashes.
4059
4060
4061
File: gnupg.info, Node: GPGSM Configuration, Next: GPGSM Examples, Prev: GPGSM Options, Up: Invoking GPGSM
4062
4063
4.3 Configuration files
4064
=======================
4065
4066
There are a few configuration files to control certain aspects of
4067
`gpgsm''s operation. Unless noted, they are expected in the current
4068
home directory (*note option --homedir::).
4069
4070
`gpgsm.conf'
4071
This is the standard configuration file read by `gpgsm' on
4072
startup. It may contain any valid long option; the leading two
4073
dashes may not be entered and the option may not be abbreviated.
4074
This default name may be changed on the command line (*note option
4075
--options::).
4076
4077
`policies.txt'
4078
This is a list of allowed CA policies. This file should list the
4079
object identifiers of the policies line by line. Empty lines and
4080
lines starting with a hash mark are ignored. Policies missing in
4081
this file and not marked as critical in the certificate will print
4082
only a warning; certificates with policies marked as critical and
4083
not listed in this file will fail the signature verification.
4084
4085
For example, to allow only the policy 2.289.9.9, the file should
4086
look like this:
4087
4088
# Allowed policies
4089
2.289.9.9
4090
4091
`qualified.txt'
4092
This is the list of root certificates used for qualified
4093
certificates. They are defined as certificates capable of
4094
creating legally binding signatures in the same way as handwritten
4095
signatures are. Comments start with a hash mark and empty lines
4096
are ignored. Lines do have a length limit but this is not a
4097
serious limitation as the format of the entries is fixed and
4098
checked by gpgsm: A non-comment line starts with optional
4099
whitespace, followed by exactly 40 hex character, white space and
4100
a lowercased 2 letter country code. Additional data delimited with
4101
by a white space is current ignored but might late be used for
4102
other purposes.
4103
4104
Note that even if a certificate is listed in this file, this does
4105
not mean that the certificate is trusted; in general the
4106
certificates listed in this file need to be listed also in
4107
`trustlist.txt'.
4108
4109
This is a global file an installed in the data directory (e.g.
4110
`/usr/share/gnupg/qualified.txt'). GnuPG installs a suitable file
4111
with root certificates as used in Germany. As new Root-CA
4112
certificates may be issued over time, these entries may need to be
4113
updated; new distributions of this software should come with an
4114
updated list but it is still the responsibility of the
4115
Administrator to check that this list is correct.
4116
4117
Everytime `gpgsm' uses a certificate for signing or verification
4118
this file will be consulted to check whether the certificate under
4119
question has ultimately been issued by one of these CAs. If this
4120
is the case the user will be informed that the verified signature
4121
represents a legally binding ("qualified") signature. When
4122
creating a signature using such a certificate an extra prompt will
4123
be issued to let the user confirm that such a legally binding
4124
signature shall really be created.
4125
4126
Because this software has not yet been approved for use with such
4127
certificates, appropriate notices will be shown to indicate this
4128
fact.
4129
4130
`help.txt'
4131
This is plain text file with a few help entries used with
4132
`pinentry' as well as a large list of help items for `gpg' and
4133
`gpgsm'. The standard file has English help texts; to install
4134
localized versions use filenames like `help.LL.txt' with LL
4135
denoting the locale. GnuPG comes with a set of predefined help
4136
files in the data directory (e.g. `/usr/share/gnupg/help.de.txt')
4137
and allows overriding of any help item by help files stored in the
4138
system configuration directory (e.g. `/etc/gnupg/help.de.txt').
4139
For a reference of the help file's syntax, please see the installed
4140
`help.txt' file.
4141
4142
4143
Note that on larger installations, it is useful to put predefined
4144
files into the directory `/etc/skel/.gnupg/' so that newly created users
4145
start up with a working configuration. For existing users the a small
4146
helper script is provided to create these files (*note addgnupghome::).
4147
4148
For internal purposes gpgsm creates and maintaines a few other files;
4149
They all live in in the current home directory (*note option
4150
--homedir::). Only `gpgsm' may modify these files.
4151
4152
`pubring.kbx'
4153
This a database file storing the certificates as well as meta
4154
information. For debugging purposes the tool `kbxutil' may be
4155
used to show the internal structure of this file.
4156
4157
`random_seed'
4158
This content of this file is used to maintain the internal state
4159
of the random number generator accross invocations. The same file
4160
is used by other programs of this software too.
4161
4162
`S.gpg-agent'
4163
If this file exists and the environment variable `GPG_AGENT_INFO'
4164
is not set, `gpgsm' will first try to connect to this socket for
4165
accessing `gpg-agent' before starting a new `gpg-agent' instance.
4166
Under Windows this socket (which in reality be a plain file
4167
describing a regular TCP litening port) is the standard way of
4168
connecting the `gpg-agent'.
4169
4170
4171
4172
File: gnupg.info, Node: GPGSM Examples, Next: Unattended Usage, Prev: GPGSM Configuration, Up: Invoking GPGSM
4173
4174
4.4 Examples
4175
============
4176
4177
$ gpgsm -er goo@bar.net <plaintext >ciphertext
4178
4179
4180
File: gnupg.info, Node: Unattended Usage, Next: GPGSM Protocol, Prev: GPGSM Examples, Up: Invoking GPGSM
4181
4182
4.5 Unattended Usage
4183
====================
4184
4185
`gpgsm' is often used as a backend engine by other software. To help
4186
with this a machine interface has been defined to have an unambiguous
4187
way to do this. This is most likely used with the `--server' command
4188
but may also be used in the standard operation mode by using the
4189
`--status-fd' option.
4190
4191
* Menu:
4192
4193
* Automated signature checking:: Automated signature checking.
4194
4195
4196
File: gnupg.info, Node: Automated signature checking, Up: Unattended Usage
4197
4198
4.6 Automated signature checking
4199
================================
4200
4201
It is very important to understand the semantics used with signature
4202
verification. Checking a signature is not as simple as it may sound and
4203
so the ooperation si a bit complicated. In mosted cases it is required
4204
to look at several status lines. Here is a table of all cases a signed
4205
message may have:
4206
4207
The signature is valid
4208
This does mean that the signature has been successfully verified,
4209
the certificates are all sane. However there are two subcases with
4210
important information: One of the certificates may have expired
4211
or a signature of a message itself as expired. It is a sound
4212
practise to consider such a signature still as valid but
4213
additional information should be displayed. Depending on the
4214
subcase `gpgsm' will issue these status codes:
4215
signature valid and nothing did expire
4216
`GOODSIG', `VALIDSIG', `TRUST_FULLY'
4217
4218
signature valid but at least one certificate has expired
4219
`EXPKEYSIG', `VALIDSIG', `TRUST_FULLY'
4220
4221
signature valid but expired
4222
`EXPSIG', `VALIDSIG', `TRUST_FULLY' Note, that this case is
4223
currently not implemented.
4224
4225
The signature is invalid
4226
This means that the signature verification failed (this is an
4227
indication of af a transfer error, a programm error or tampering
4228
with the message). `gpgsm' issues one of these status codes
4229
sequences:
4230
``BADSIG''
4231
4232
``GOODSIG', `VALIDSIG' `TRUST_NEVER''
4233
4234
Error verifying a signature
4235
For some reason the signature could not be verified, i.e. it can't
4236
be decided whether the signature is valid or invalid. A common
4237
reason for this is a missing certificate.
4238
4239
4240
4241
File: gnupg.info, Node: GPGSM Protocol, Prev: Unattended Usage, Up: Invoking GPGSM
4242
4243
4.7 The Protocol the Server Mode Uses.
4244
======================================
4245
4246
Description of the protocol used to access `GPGSM'. `GPGSM' does
4247
implement the Assuan protocol and in addition provides a regular
4248
command line interface which exhibits a full client to this protocol
4249
(but uses internal linking). To start `gpgsm' as a server the command
4250
line the option `--server' must be used. Additional options are
4251
provided to select the communication method (i.e. the name of the
4252
socket).
4253
4254
We assume that the connection has already been established; see the
4255
Assuan manual for details.
4256
4257
* Menu:
4258
4259
* GPGSM ENCRYPT:: Encrypting a message.
4260
* GPGSM DECRYPT:: Decrypting a message.
4261
* GPGSM SIGN:: Signing a message.
4262
* GPGSM VERIFY:: Verifying a message.
4263
* GPGSM GENKEY:: Generating a key.
4264
* GPGSM LISTKEYS:: List available keys.
4265
* GPGSM EXPORT:: Export certificates.
4266
* GPGSM IMPORT:: Import certificates.
4267
* GPGSM DELETE:: Delete certificates.
4268
* GPGSM GETINFO:: Information about the process
4269
4270
4271
File: gnupg.info, Node: GPGSM ENCRYPT, Next: GPGSM DECRYPT, Up: GPGSM Protocol
4272
4273
4.7.1 Encrypting a Message
4274
--------------------------
4275
4276
Before encrytion can be done the recipient must be set using the
4277
command:
4278
4279
RECIPIENT USERID
4280
4281
Set the recipient for the encryption. USERID should be the internal
4282
representation of the key; the server may accept any other way of
4283
specification. If this is a valid and trusted recipient the server
4284
does respond with OK, otherwise the return is an ERR with the reason why
4285
the recipient can't be used, the encryption will then not be done for
4286
this recipient. If the policy is not to encrypt at all if not all
4287
recipients are valid, the client has to take care of this. All
4288
`RECIPIENT' commands are cumulative until a `RESET' or an successful
4289
`ENCRYPT' command.
4290
4291
INPUT FD[=N] [--armor|--base64|--binary]
4292
4293
Set the file descriptor for the message to be encrypted to N.
4294
Obviously the pipe must be open at that point, the server establishes
4295
its own end. If the server returns an error the client should consider
4296
this session failed. If N is not given, this commands uses the last
4297
file descriptor passed to the application. *Note the assuan_sendfd
4298
function: (assuan)fun-assuan_sendfd, on how to do descriptor passing.
4299
4300
The `--armor' option may be used to advice the server that the input
4301
data is in PEM format, `--base64' advices that a raw base-64 encoding
4302
is used, `--binary' advices of raw binary input (BER). If none of
4303
these options is used, the server tries to figure out the used
4304
encoding, but this may not always be correct.
4305
4306
OUTPUT FD[=N] [--armor|--base64]
4307
4308
Set the file descriptor to be used for the output (i.e. the encrypted
4309
message). Obviously the pipe must be open at that point, the server
4310
establishes its own end. If the server returns an error he client
4311
should consider this session failed.
4312
4313
The option armor encodes the output in PEM format, the `--base64'
4314
option applies just a base 64 encoding. No option creates binary
4315
output (BER).
4316
4317
The actual encryption is done using the command
4318
4319
ENCRYPT
4320
4321
It takes the plaintext from the `INPUT' command, writes to the
4322
ciphertext to the file descriptor set with the `OUTPUT' command, take
4323
the recipients from all the recipients set so far. If this command
4324
fails the clients should try to delete all output currently done or
4325
otherwise mark it as invalid. `GPGSM' does ensure that there won't be
4326
any security problem with leftover data on the output in this case.
4327
4328
This command should in general not fail, as all necessary checks have
4329
been done while setting the recipients. The input and output pipes are
4330
closed.
4331
4332
4333
File: gnupg.info, Node: GPGSM DECRYPT, Next: GPGSM SIGN, Prev: GPGSM ENCRYPT, Up: GPGSM Protocol
4334
4335
4.7.2 Decrypting a message
4336
--------------------------
4337
4338
Input and output FDs are set the same way as in encryption, but `INPUT'
4339
refers to the ciphertext and output to the plaintext. There is no need
4340
to set recipients. `GPGSM' automatically strips any S/MIME headers
4341
from the input, so it is valid to pass an entire MIME part to the INPUT
4342
pipe.
4343
4344
The encryption is done by using the command
4345
4346
DECRYPT
4347
4348
It performs the decrypt operation after doing some check on the
4349
internal state. (e.g. that all needed data has been set). Because it
4350
utilizes the GPG-Agent for the session key decryption, there is no need
4351
to ask the client for a protecting passphrase - GpgAgent takes care of
4352
this by requesting this from the user.
4353
4354
4355
File: gnupg.info, Node: GPGSM SIGN, Next: GPGSM VERIFY, Prev: GPGSM DECRYPT, Up: GPGSM Protocol
4356
4357
4.7.3 Signing a Message
4358
-----------------------
4359
4360
Signing is usually done with these commands:
4361
4362
INPUT FD[=N] [--armor|--base64|--binary]
4363
4364
This tells `GPGSM' to read the data to sign from file descriptor N.
4365
4366
OUTPUT FD[=M] [--armor|--base64]
4367
4368
Write the output to file descriptor M. If a detached signature is
4369
requested, only the signature is written.
4370
4371
SIGN [--detached]
4372
4373
Sign the data set with the INPUT command and write it to the sink
4374
set by OUTPUT. With `--detached', a detached signature is created
4375
(surprise).
4376
4377
The key used for signining is the default one or the one specified in
4378
the configuration file. To get finer control over the keys, it is
4379
possible to use the command
4380
4381
SIGNER USERID
4382
4383
to the signer's key. USERID should be the internal representation
4384
of the key; the server may accept any other way of specification. If
4385
this is a valid and trusted recipient the server does respond with OK,
4386
otherwise the return is an ERR with the reason why the key can't be
4387
used, the signature will then not be created using this key. If the
4388
policy is not to sign at all if not all keys are valid, the client has
4389
to take care of this. All `SIGNER' commands are cumulative until a
4390
`RESET' is done. Note that a `SIGN' does not reset this list of
4391
signers which is in contrats to the `RECIPIENT' command.
4392
4393
4394
File: gnupg.info, Node: GPGSM VERIFY, Next: GPGSM GENKEY, Prev: GPGSM SIGN, Up: GPGSM Protocol
4395
4396
4.7.4 Verifying a Message
4397
-------------------------
4398
4399
To verify a mesage the command:
4400
4401
VERIFY
4402
4403
is used. It does a verify operation on the message send to the input
4404
FD. The result is written out using status lines. If an output FD was
4405
given, the signed text will be written to that. If the signature is a
4406
detached one, the server will inquire about the signed material and the
4407
client must provide it.
4408
4409
4410
File: gnupg.info, Node: GPGSM GENKEY, Next: GPGSM LISTKEYS, Prev: GPGSM VERIFY, Up: GPGSM Protocol
4411
4412
4.7.5 Generating a Key
4413
----------------------
4414
4415
This is used to generate a new keypair, store the secret part in the
4416
PSE and the public key in the key database. We will probably add
4417
optional commands to allow the client to select whether a hardware
4418
token is used to store the key. Configuration options to `GPGSM' can
4419
be used to restrict the use of this command.
4420
4421
GENKEY
4422
4423
`GPGSM' checks whether this command is allowed and then does an
4424
INQUIRY to get the key parameters, the client should then send the key
4425
parameters in the native format:
4426
4427
S: INQUIRE KEY_PARAM native
4428
C: D foo:fgfgfg
4429
C: D bar
4430
C: END
4431
4432
Please note that the server may send Status info lines while reading
4433
the data lines from the client. After this the key generation takes
4434
place and the server eventually does send an ERR or OK response.
4435
Status lines may be issued as a progress indicator.
4436
4437
4438
File: gnupg.info, Node: GPGSM LISTKEYS, Next: GPGSM EXPORT, Prev: GPGSM GENKEY, Up: GPGSM Protocol
4439
4440
4.7.6 List available keys
4441
-------------------------
4442
4443
To list the keys in the internal database or using an external key
4444
provider, the command:
4445
4446
LISTKEYS PATTERN
4447
4448
is used. To allow multiple patterns (which are ORed during the
4449
search) quoting is required: Spaces are to be translated into "+" or
4450
into "%20"; in turn this requires that the usual escape quoting rules
4451
are done.
4452
4453
LISTSECRETKEYS PATTERN
4454
4455
Lists only the keys where a secret key is available.
4456
4457
The list commands commands are affected by the option
4458
4459
OPTION list-mode=MODE
4460
4461
where mode may be:
4462
`0'
4463
Use default (which is usually the same as 1).
4464
4465
`1'
4466
List only the internal keys.
4467
4468
`2'
4469
List only the external keys.
4470
4471
`3'
4472
List internal and external keys.
4473
4474
Note that options are valid for the entire session.
4475
4476
4477
File: gnupg.info, Node: GPGSM EXPORT, Next: GPGSM IMPORT, Prev: GPGSM LISTKEYS, Up: GPGSM Protocol
4478
4479
4.7.7 Export certificates
4480
-------------------------
4481
4482
To export certificate from the internal key database the command:
4483
4484
EXPORT [--data [--armor] [--base64]] [--] PATTERN
4485
4486
is used. To allow multiple patterns (which are ORed) quoting is
4487
required: Spaces are to be translated into "+" or into "%20"; in turn
4488
this requires that the usual escape quoting rules are done.
4489
4490
If the `--data' option has not been given, the format of the output
4491
depends on what was set with the OUTPUT command. When using PEM
4492
encoding a few informational lines are prepended.
4493
4494
If the `--data' has been given, a target set via OUTPUT is ignored
4495
and the data is returned inline using standard `D'-lines. This avoids
4496
the need for an extra file descriptor. In this case the options
4497
`--armor' and `--base64' may be used in the same way as with the OUTPUT
4498
command.
4499
4500
4501
File: gnupg.info, Node: GPGSM IMPORT, Next: GPGSM DELETE, Prev: GPGSM EXPORT, Up: GPGSM Protocol
4502
4503
4.7.8 Import certificates
4504
-------------------------
4505
4506
To import certificates into the internal key database, the command
4507
4508
IMPORT
4509
4510
is used. The data is expected on the file descriptor set with the
4511
`INPUT' command. Certain checks are performend on the certificate.
4512
Note that the code will also handle PKCS\#12 files and import private
4513
keys; a helper program is used for that.
4514
4515
4516
File: gnupg.info, Node: GPGSM DELETE, Next: GPGSM GETINFO, Prev: GPGSM IMPORT, Up: GPGSM Protocol
4517
4518
4.7.9 Delete certificates
4519
-------------------------
4520
4521
To delete a certificate the command
4522
4523
DELKEYS PATTERN
4524
4525
is used. To allow multiple patterns (which are ORed) quoting is
4526
required: Spaces are to be translated into "+" or into "%20"; in turn
4527
this requires that the usual escape quoting rules are done.
4528
4529
The certificates must be specified unambiguously otherwise an error
4530
is returned.
4531
4532
4533
File: gnupg.info, Node: GPGSM GETINFO, Prev: GPGSM DELETE, Up: GPGSM Protocol
4534
4535
4.7.10 Return information about the process
4536
-------------------------------------------
4537
4538
This is a multipurpose function to return a variety of information.
4539
4540
GETINFO WHAT
4541
4542
The value of WHAT specifies the kind of information returned:
4543
`version'
4544
Return the version of the program.
4545
4546
`pid'
4547
Return the process id of the process.
4548
4549
4550
File: gnupg.info, Node: Invoking SCDAEMON, Next: Specify a User ID, Prev: Invoking GPGSM, Up: Top
4551
4552
5 Invoking the SCDAEMON
4553
***********************
4554
4555
The `scdaemon' is a daemon to manage smartcards. It is usually invoked
4556
by `gpg-agent' and in general not used directly.
4557
4558
*Note Option Index::, for an index to `scdaemon''s commands and
4559
options.
4560
4561
* Menu:
4562
4563
* Scdaemon Commands:: List of all commands.
4564
* Scdaemon Options:: List of all options.
4565
* Card applications:: Description of card applications.
4566
* Scdaemon Configuration:: Configuration files.
4567
* Scdaemon Examples:: Some usage examples.
4568
* Scdaemon Protocol:: The protocol the daemon uses.
4569
4570
4571
File: gnupg.info, Node: Scdaemon Commands, Next: Scdaemon Options, Up: Invoking SCDAEMON
4572
4573
5.1 Commands
4574
============
4575
4576
Commands are not distinguished from options except for the fact that
4577
only one command is allowed.
4578
4579
`--version'
4580
Print the program version and licensing information. Not that you
4581
can abbreviate this command.
4582
4583
`--help, -h'
4584
Print a usage message summarizing the most usefule command-line
4585
options. Not that you can abbreviate this command.
4586
4587
`--dump-options'
4588
Print a list of all available options and commands. Not that you
4589
can abbreviate this command.
4590
4591
`--server'
4592
Run in server mode and wait for commands on the `stdin'. This is
4593
default mode is to create a socket and listen for commands there.
4594
4595
`--multi-server'
4596
Run in server mode and wait for commands on the `stdin' as well as
4597
on an additional Unix Domain socket. The server command `GETINFO'
4598
may be used to get the name of that extra socket.
4599
4600
`--daemon'
4601
Run the program in the background. This option is required to
4602
prevent it from being accidently running in the background.
4603
4604
4605
4606
File: gnupg.info, Node: Scdaemon Options, Next: Card applications, Prev: Scdaemon Commands, Up: Invoking SCDAEMON
4607
4608
5.2 Option Summary
4609
==================
4610
4611
`--options FILE'
4612
Reads configuration from FILE instead of from the default per-user
4613
configuration file. The default configuration file is named
4614
`scdaemon.conf' and expected in the `.gnupg' directory directly
4615
below the home directory of the user.
4616
4617
`--homedir DIR'
4618
Set the name of the home directory to DIR. If his option is not
4619
used, the home directory defaults to `~/.gnupg'. It is only
4620
recognized when given on the command line. It also overrides any
4621
home directory stated through the environment variable `GNUPGHOME'
4622
or (on W32 systems) by means on the Registry entry
4623
HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
4624
4625
`-v'
4626
4627
`--verbose'
4628
Outputs additional information while running. You can increase
4629
the verbosity by giving several verbose commands to `gpgsm', such
4630
as `-vv'.
4631
4632
`--debug-level LEVEL'
4633
Select the debug level for investigating problems. LEVEL may be
4634
one of:
4635
4636
`none'
4637
no debugging at all.
4638
4639
`basic'
4640
some basic debug messages
4641
4642
`advanced'
4643
more verbose debug messages
4644
4645
`expert'
4646
even more detailed messages
4647
4648
`guru'
4649
all of the debug messages you can get
4650
4651
How these messages are mapped to the actual debugging flags is not
4652
specified and may change with newer releases of this program. They
4653
are however carefully selected to best aid in debugging.
4654
4655
Note: All debugging options are subject to change and thus
4656
should not be used by any application program. As the name
4657
says, they are only used as helpers to debug problems.
4658
4659
`--debug FLAGS'
4660
This option is only useful for debugging and the behaviour may
4661
change at any time without notice. FLAGS are bit encoded and may
4662
be given in usual C-Syntax. The currently defined bits are:
4663
4664
`0 (1)'
4665
command I/O
4666
4667
`1 (2)'
4668
values of big number integers
4669
4670
`2 (4)'
4671
low level crypto operations
4672
4673
`5 (32)'
4674
memory allocation
4675
4676
`6 (64)'
4677
caching
4678
4679
`7 (128)'
4680
show memory statistics.
4681
4682
`9 (512)'
4683
write hashed data to files named `dbgmd-000*'
4684
4685
`10 (1024)'
4686
trace Assuan protocol
4687
4688
`11 (2048)'
4689
trace APDU I/O to the card. This may reveal sensitive data.
4690
4691
`--debug-all'
4692
Same as `--debug=0xffffffff'
4693
4694
`--debug-wait N'
4695
When running in server mode, wait N seconds before entering the
4696
actual processing loop and print the pid. This gives time to
4697
attach a debugger.
4698
4699
`--debug-ccid-driver'
4700
Enable debug output from the included CCID driver for smartcards.
4701
Using this option twice will also enable some tracing of the T=1
4702
protocol. Note that this option may reveal sensitive data.
4703
4704
`--debug-disable-ticker'
4705
This option disables all ticker functions like checking for card
4706
insertions.
4707
4708
`--debug-allow-core-dump'
4709
For security reasons we won't create a core dump when the process
4710
aborts. For debugging purposes it is sometimes better to allow
4711
core dump. This options enables it and also changes the working
4712
directory to `/tmp' when running in `--server' mode.
4713
4714
`--no-detach'
4715
Don't detach the process from the console. This is mainly useful
4716
for debugging.
4717
4718
`--log-file FILE'
4719
Append all logging output to FILE. This is very helpful in seeing
4720
what the agent actually does.
4721
4722
`--pcsc-driver LIBRARY'
4723
Use LIBRARY to access the smartcard reader. The current default
4724
is `libpcsclite.so'. Instead of using this option you might also
4725
want to install a symbolic link to the default file name (e.g.
4726
from `libpcsclite.so.1').
4727
4728
`--ctapi-driver LIBRARY'
4729
Use LIBRARY to access the smartcard reader. The current default
4730
is `libtowitoko.so'. Note that the use of this interface is
4731
deprecated; it may be removed in future releases.
4732
4733
`--disable-ccid'
4734
Disable the integrated support for CCID compliant readers. This
4735
allows to fall back to one of the other drivers even if the
4736
internal CCID driver can handle the reader. Note, that CCID
4737
support is only available if libusb was available at build time.
4738
4739
`--reader-port NUMBER_OR_STRING'
4740
This option may be used to specify the port of the card terminal.
4741
A value of 0 refers to the first serial device; add 32768 to
4742
access USB devices. The default is 32768 (first USB device).
4743
PC/SC or CCID readers might need a string here; run the program in
4744
verbose mode to get a list of available readers. The default is
4745
then the first reader found.
4746
4747
To get a list of available CCID readers you may use this command:
4748
echo scd getinfo reader_list | gpg-connect-agent --decode | awk '/^D/ {print $2}'
4749
4750
`--disable-keypad'
4751
Even if a card reader features a keypad, do not try to use it.
4752
4753
`--allow-admin'
4754
`--deny-admin'
4755
This enables the use of Admin class commands for card applications
4756
where this is supported. Currently we support it for the OpenPGP
4757
card. Deny is the default. This commands is useful to inhibit
4758
accidental access to admin class command which could ultimately
4759
lock the card through worng PIN numbers.
4760
4761
`--disable-application NAME'
4762
This option disables the use of the card application named NAME.
4763
This is mainly useful for debugging or if a application with lower
4764
priority should be used by default.
4765
4766
4767
All the long options may also be given in the configuration file
4768
after stripping off the two leading dashes.
4769
4770
4771
File: gnupg.info, Node: Card applications, Next: Scdaemon Configuration, Prev: Scdaemon Options, Up: Invoking SCDAEMON
4772
4773
5.3 Description of card applications
4774
====================================
4775
4776
`scdaemon' supports the card applications as described below.
4777
4778
* Menu:
4779
4780
* OpenPGP Card:: The OpenPGP card application
4781
* NKS Card:: The Telesec NetKey card application
4782
* DINSIG Card:: The DINSIG card application
4783
* PKCS#15 Card:: The PKCS#15 card application
4784
4785
4786
File: gnupg.info, Node: OpenPGP Card, Next: NKS Card, Up: Card applications
4787
4788
5.3.1 The OpenPGP card application "openpgp"
4789
--------------------------------------------
4790
4791
This application is currently only used by `gpg' but may in future also
4792
be useful with `gpgsm'.
4793
4794
The specification for such a card is available at
4795
`http://g10code.com/docs/openpgp-card-1.0.pdf'.
4796
4797
4798
File: gnupg.info, Node: NKS Card, Next: DINSIG Card, Prev: OpenPGP Card, Up: Card applications
4799
4800
5.3.2 The Telesec NetKey card "nks"
4801
-----------------------------------
4802
4803
This is the main application of the Telesec cards as available in
4804
Germany. It is a superset of the German DINSIG card. The card is used
4805
by `gpgsm'.
4806
4807
4808
File: gnupg.info, Node: DINSIG Card, Next: PKCS#15 Card, Prev: NKS Card, Up: Card applications
4809
4810
5.3.3 The DINSIG card application "dinsig"
4811
------------------------------------------
4812
4813
This is an application as described in the German draft standard _DIN V
4814
66291-1_. It is intended to be used by cards supporting the German
4815
signature law and its bylaws (SigG and SigV).
4816
4817
4818
File: gnupg.info, Node: PKCS#15 Card, Prev: DINSIG Card, Up: Card applications
4819
4820
5.3.4 The PKCS#15 card application "p15"
4821
----------------------------------------
4822
4823
This is common fraqmework for smart card applications. It is used by
4824
`gpgsm'.
4825
4826
4827
File: gnupg.info, Node: Scdaemon Configuration, Next: Scdaemon Examples, Prev: Card applications, Up: Invoking SCDAEMON
4828
4829
5.4 Configuration files
4830
=======================
4831
4832
There are a few configuration files to control certain aspects of
4833
`scdaemons''s operation. Unless noted, they are expected in the current
4834
home directory (*note option --homedir::).
4835
4836
`scdaemon.conf'
4837
This is the standard configuration file read by `scdaemon' on
4838
startup. It may contain any valid long option; the leading two
4839
dashes may not be entered and the option may not be abbreviated.
4840
This default name may be changed on the command line (*note option
4841
--options::).
4842
4843
`scd-event'
4844
If this file is present and executable, it will be called on veyer
4845
card reader's status changed. An example of this script is
4846
provided with the distribution
4847
4848
`reader_N.status'
4849
This file is created by `sdaemon' to let other applications now
4850
about reader status changes. Its use is now deprecated in favor of
4851
`scd-event'.
4852
4853
4854
4855
File: gnupg.info, Node: Scdaemon Examples, Next: Scdaemon Protocol, Prev: Scdaemon Configuration, Up: Invoking SCDAEMON
4856
4857
5.5 Examples
4858
============
4859
4860
$ scdaemon --server -v
4861
4862
4863
File: gnupg.info, Node: Scdaemon Protocol, Prev: Scdaemon Examples, Up: Invoking SCDAEMON
4864
4865
5.6 Scdaemon's Assuan Protocol
4866
==============================
4867
4868
The SC-Daemon should be started by the system to provide access to
4869
external tokens. Using Smartcards on a multi-user system does not make
4870
much sense expcet for system services, but in this case no regular user
4871
accounts are hosted on the machine.
4872
4873
A client connects to the SC-Daemon by connecting to the socket named
4874
`/var/run/scdaemon/socket', configuration information is read from
4875
/ETC/SCDAEMON.CONF
4876
4877
Each connection acts as one session, SC-Daemon takes care of
4878
syncronizing access to a token between sessions.
4879
4880
* Menu:
4881
4882
* Scdaemon SERIALNO:: Return the serial number.
4883
* Scdaemon LEARN:: Read all useful information from the card.
4884
* Scdaemon READCERT:: Return a certificate.
4885
* Scdaemon READKEY:: Return a public key.
4886
* Scdaemon PKSIGN:: Signing data with a Smartcard.
4887
* Scdaemon PKDECRYPT:: Decrypting data with a Smartcard.
4888
* Scdaemon GETATTR:: Read an attribute's value.
4889
* Scdaemon SETATTR:: Update an attribute's value.
4890
* Scdaemon WRITEKEY:: Write a key to a card.
4891
* Scdaemon GENKEY:: Generate a new key on-card.
4892
* Scdaemon RANDOM:: Return random bytes generate on-card.
4893
* Scdaemon PASSWD:: Change PINs.
4894
* Scdaemon CHECKPIN:: Perform a VERIFY operation.
4895
* Scdaemon RESTART:: Restart connection
4896
* Scdaemon APDU:: Send a verbatim APDU to the card
4897
4898
4899
File: gnupg.info, Node: Scdaemon SERIALNO, Next: Scdaemon LEARN, Up: Scdaemon Protocol
4900
4901
5.6.1 Return the serial number
4902
------------------------------
4903
4904
This command should be used to check for the presence of a card. It is
4905
special in that it can be used to reset the card. Most other commands
4906
will return an error when a card change has been detected and the use of
4907
this function is therefore required.
4908
4909
Background: We want to keep the client clear of handling card changes
4910
between operations; i.e. the client can assume that all operations are
4911
done on the same card unless he call this function.
4912
4913
SERIALNO
4914
4915
Return the serial number of the card using a status reponse like:
4916
4917
S SERIALNO D27600000000000000000000 0
4918
4919
The trailing 0 should be ignored for now, it is reserved for a future
4920
extension. The serial number is the hex encoded value identified by
4921
the `0x5A' tag in the GDO file (FIX=0x2F02).
4922
4923
4924
File: gnupg.info, Node: Scdaemon LEARN, Next: Scdaemon READCERT, Prev: Scdaemon SERIALNO, Up: Scdaemon Protocol
4925
4926
5.6.2 Read all useful information from the card
4927
-----------------------------------------------
4928
4929
LEARN [--force]
4930
4931
Learn all useful information of the currently inserted card. When
4932
used without the force options, the command might do an INQUIRE like
4933
this:
4934
4935
INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
4936
4937
The client should just send an `END' if the processing should go on
4938
or a `CANCEL' to force the function to terminate with a cancel error
4939
message. The response of this command is a list of status lines
4940
formatted as this:
4941
4942
S KEYPAIRINFO HEXSTRING_WITH_KEYGRIP HEXSTRING_WITH_ID
4943
4944
If there is no certificate yet stored on the card a single "X" is
4945
returned in HEXSTRING_WITH_KEYGRIP.
4946
4947
4948
File: gnupg.info, Node: Scdaemon READCERT, Next: Scdaemon READKEY, Prev: Scdaemon LEARN, Up: Scdaemon Protocol
4949
4950
5.6.3 Return a certificate
4951
--------------------------
4952
4953
READCERT HEXIFIED_CERTID
4954
4955
This function is used to read a certificate identified by
4956
HEXIFIED_CERTID from the card.
4957
4958
4959
File: gnupg.info, Node: Scdaemon READKEY, Next: Scdaemon PKSIGN, Prev: Scdaemon READCERT, Up: Scdaemon Protocol
4960
4961
5.6.4 Return a public key
4962
-------------------------
4963
4964
READKEY HEXIFIED_CERTID
4965
4966
Return the public key for the given cert or key ID as an standard
4967
S-Expression.
4968
4969
4970
File: gnupg.info, Node: Scdaemon PKSIGN, Next: Scdaemon PKDECRYPT, Prev: Scdaemon READKEY, Up: Scdaemon Protocol
4971
4972
5.6.5 Signing data with a Smartcard
4973
-----------------------------------
4974
4975
To sign some data the caller should use the command
4976
4977
SETDATA HEXSTRING
4978
4979
to tell `scdaemon' about the data to be signed. The data must be
4980
given in hex notation. The actual signing is done using the command
4981
4982
PKSIGN KEYID
4983
4984
where KEYID is the hexified ID of the key to be used. The key id
4985
may have been retrieved using the command `LEARN'. If another hash
4986
algorithm than SHA-1 is used, that algorithm may be given like:
4987
4988
PKSIGN --hash=ALGONAME KEYID
4989
4990
With ALGONAME are one of `sha1', `rmd160' or `md5'.
4991
4992
4993
File: gnupg.info, Node: Scdaemon PKDECRYPT, Next: Scdaemon GETATTR, Prev: Scdaemon PKSIGN, Up: Scdaemon Protocol
4994
4995
5.6.6 Decrypting data with a Smartcard
4996
--------------------------------------
4997
4998
To decrypt some data the caller should use the command
4999
5000
SETDATA HEXSTRING
5001
5002
to tell `scdaemon' about the data to be decrypted. The data must be
5003
given in hex notation. The actual decryption is then done using the
5004
command
5005
5006
PKDECRYPT KEYID
5007
5008
where KEYID is the hexified ID of the key to be used.
5009
5010
5011
File: gnupg.info, Node: Scdaemon GETATTR, Next: Scdaemon SETATTR, Prev: Scdaemon PKDECRYPT, Up: Scdaemon Protocol
5012
5013
5.6.7 Read an attribute's value.
5014
--------------------------------
5015
5016
TO BE WRITTEN.
5017
5018
5019
File: gnupg.info, Node: Scdaemon SETATTR, Next: Scdaemon WRITEKEY, Prev: Scdaemon GETATTR, Up: Scdaemon Protocol
5020
5021
5.6.8 Update an attribute's value.
5022
----------------------------------
5023
5024
TO BE WRITTEN.
5025
5026
5027
File: gnupg.info, Node: Scdaemon WRITEKEY, Next: Scdaemon GENKEY, Prev: Scdaemon SETATTR, Up: Scdaemon Protocol
5028
5029
5.6.9 Write a key to a card.
5030
----------------------------
5031
5032
WRITEKEY [--force] KEYID
5033
5034
This command is used to store a secret key on a a smartcard. The
5035
allowed keyids depend on the currently selected smartcard application.
5036
The actual keydata is requested using the inquiry `KEYDATA' and need to
5037
be provided without any protection. With `--force' set an existing key
5038
under this KEYID will get overwritten. The key data is expected to be
5039
the usual canonical encoded S-expression.
5040
5041
A PIN will be requested in most saes. This however depends on the
5042
actual card application.
5043
5044
5045
File: gnupg.info, Node: Scdaemon GENKEY, Next: Scdaemon RANDOM, Prev: Scdaemon WRITEKEY, Up: Scdaemon Protocol
5046
5047
5.6.10 Generate a new key on-card.
5048
----------------------------------
5049
5050
TO BE WRITTEN.
5051
5052
5053
File: gnupg.info, Node: Scdaemon RANDOM, Next: Scdaemon PASSWD, Prev: Scdaemon GENKEY, Up: Scdaemon Protocol
5054
5055
5.6.11 Return random bytes generate on-card.
5056
--------------------------------------------
5057
5058
TO BE WRITTEN.
5059
5060
5061
File: gnupg.info, Node: Scdaemon PASSWD, Next: Scdaemon CHECKPIN, Prev: Scdaemon RANDOM, Up: Scdaemon Protocol
5062
5063
5.6.12 Change PINs.
5064
-------------------
5065
5066
PASSWD [--reset] CHVNO
5067
5068
Change the PIN or reset the retry counter of the card holder
5069
verification vector number CHVNO.
5070
5071
5072
File: gnupg.info, Node: Scdaemon CHECKPIN, Next: Scdaemon RESTART, Prev: Scdaemon PASSWD, Up: Scdaemon Protocol
5073
5074
5.6.13 Perform a VERIFY operation.
5075
----------------------------------
5076
5077
CHECKPIN IDSTR
5078
5079
Perform a VERIFY operation without doing anything else. This may be
5080
used to initialize a the PIN cache earlier to long lasting operations.
5081
Its use is highly application dependent:
5082
5083
*OpenPGP*
5084
Perform a simple verify operation for CHV1 and CHV2, so that
5085
further operations won't ask for CHV2 and it is possible to do a
5086
cheap check on the PIN: If there is something wrong with the PIN
5087
entry system, only the regular CHV will get blocked and not the
5088
dangerous CHV3. IDSTR is the usual card's serial number in hex
5089
notation; an optional fingerprint part will get ignored.
5090
5091
There is however a special mode if IDSTR is suffixed with the
5092
literal string `[CHV3]': In this case the Admin PIN is checked if
5093
and only if the retry counter is still at 3.
5094
5095
5096
5097
File: gnupg.info, Node: Scdaemon RESTART, Next: Scdaemon APDU, Prev: Scdaemon CHECKPIN, Up: Scdaemon Protocol
5098
5099
5.6.14 Perform a RESTART operation.
5100
-----------------------------------
5101
5102
RESTART
5103
5104
Restart the current connection; this is a kind of warm reset. It
5105
deletes the context used by this connection but does not actually reset
5106
the card.
5107
5108
This is used by gpg-agent to reuse a primary pipe connection and may
5109
be used by clients to backup from a conflict in the serial command;
5110
i.e. to select another application.
5111
5112
5113
File: gnupg.info, Node: Scdaemon APDU, Prev: Scdaemon RESTART, Up: Scdaemon Protocol
5114
5115
5.6.15 Send a verbatim APDU to the card.
5116
----------------------------------------
5117
5118
APDU [--atr] [--more] [HEXSTRING]
5119
5120
Send an APDU to the current reader. This command bypasses the high
5121
level functions and sends the data directly to the card. HEXSTRING is
5122
expected to be a proper APDU. If HEXSTRING is not given no commands
5123
are send to the card; However the command will implicitly check whether
5124
the card is ready for use.
5125
5126
Using the option `--atr' returns the ATR of the card as a status
5127
message before any data like this:
5128
S CARD-ATR 3BFA1300FF813180450031C173C00100009000B1
5129
5130
Using the option `--more' handles the card status word MORE_DATA
5131
(61xx) and concatenate all reponses to one block.
5132
5133
5134
File: gnupg.info, Node: Specify a User ID, Next: Helper Tools, Prev: Invoking SCDAEMON, Up: Top
5135
5136
6 How to Specify a User Id
5137
**************************
5138
5139
There are different ways to specify a user ID to GnuPG. Some of them
5140
are only valid for `gpg' others are only good for `gpgsm'. Here is the
5141
entire list of ways to specify a key:
5142
5143
* By key Id. This format is deduced from the length of the string
5144
and its content or `0x' prefix. The key Id of an X.509 certificate
5145
are the low 64 bits of its SHA-1 fingerprint. The use of key Ids
5146
is just a shortcut, for all automated processing the fingerprint
5147
should be used.
5148
5149
When using `gpg' an exclamation mark (!) may be appended to force
5150
using the specified primary or secondary key and not to try and
5151
calculate which primary or secondary key to use.
5152
5153
The last four lines of the example give the key ID in their long
5154
form as internally used by the OpenPGP protocol. You can see the
5155
long key ID using the option `--with-colons'.
5156
5157
234567C4
5158
0F34E556E
5159
01347A56A
5160
0xAB123456
5161
5162
234AABBCC34567C4
5163
0F323456784E56EAB
5164
01AB3FED1347A5612
5165
0x234AABBCC34567C4
5166
5167
* By fingerprint. This format is deduced from the length of the
5168
string and its content or the `0x' prefix. Note, that only the 20
5169
byte version fingerprint is available with `gpgsm' (i.e. the SHA-1
5170
hash of the certificate).
5171
5172
When using `gpg' an exclamation mark (!) may be appended to force
5173
using the specified primary or secondary key and not to try and
5174
calculate which primary or secondary key to use.
5175
5176
The best way to specify a key Id is by using the fingerprint. This
5177
avoids any ambiguities in case that there are duplicated key IDs.
5178
5179
1234343434343434C434343434343434
5180
123434343434343C3434343434343734349A3434
5181
0E12343434343434343434EAB3484343434343434
5182
0xE12343434343434343434EAB3484343434343434
5183
5184
(`gpgsm' also accepts colons between each pair of hexadecimal
5185
digits because this is the de-facto standard on how to present
5186
X.509 fingerprints.)
5187
5188
* By exact match on OpenPGP user ID. This is denoted by a leading
5189
equal sign. It does not make sense for X.509 certificates.
5190
5191
=Heinrich Heine <heinrichh@uni-duesseldorf.de>
5192
5193
* By exact match on an email address. This is indicated by
5194
enclosing the email address in the usual way with left and right
5195
angles.
5196
5197
<heinrichh@uni-duesseldorf.de>
5198
5199
* By word match. All words must match exactly (not case sensitive)
5200
but can appear in any order in the user ID or a subjects name.
5201
Words are any sequences of letters, digits, the underscore and all
5202
characters with bit 7 set.
5203
5204
+Heinrich Heine duesseldorf
5205
5206
* By exact match on the subject's DN. This is indicated by a
5207
leading slash, directly followed by the RFC-2253 encoded DN of the
5208
subject. Note that you can't use the string printed by "gpgsm
5209
-list-keys" because that one as been reordered and modified for
5210
better readability; use -with-colons to print the raw (but standard
5211
escaped) RFC-2253 string
5212
5213
/CN=Heinrich Heine,O=Poets,L=Paris,C=FR
5214
5215
* By exact match on the issuer's DN. This is indicated by a leading
5216
hash mark, directly followed by a slash and then directly followed
5217
by the rfc2253 encoded DN of the issuer. This should return the
5218
Root cert of the issuer. See note above.
5219
5220
#/CN=Root Cert,O=Poets,L=Paris,C=FR
5221
5222
* By exact match on serial number and issuer's DN. This is
5223
indicated by a hash mark, followed by the hexadecimal
5224
representation of the serial number, then followed by a slash and
5225
the RFC-2253 encoded DN of the issuer. See note above.
5226
5227
#4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
5228
5229
* By keygrip This is indicated by an ampersand followed by the 40
5230
hex digits of a keygrip. `gpgsm' prints the keygrip when using
5231
the command `--dump-cert'. It does not yet work for OpenPGP keys.
5232
5233
&D75F22C3F86E355877348498CDC92BD21010A480
5234
5235
* By substring match. This is the default mode but applications may
5236
want to explicitly indicate this by putting the asterisk in front.
5237
Match is not case sensitive.
5238
5239
Heine
5240
*Heine
5241
5242
5243
Please note that we have reused the hash mark identifier which was
5244
used in old GnuPG versions to indicate the so called local-id. It is
5245
not anymore used and there should be no conflict when used with X.509
5246
stuff.
5247
5248
Using the RFC-2253 format of DNs has the drawback that it is not
5249
possible to map them back to the original encoding, however we don't
5250
have to do this because our key database stores this encoding as meta
5251
data.
5252
5253
5254
File: gnupg.info, Node: Helper Tools, Next: Howtos, Prev: Specify a User ID, Up: Top
5255
5256
7 Helper Tools
5257
**************
5258
5259
GnuPG comes with a couple of smaller tools:
5260
5261
* Menu:
5262
5263
* watchgnupg:: Read logs from a socket.
5264
* gpgv:: Verify OpenPGP signatures.
5265
* addgnupghome:: Create .gnupg home directories.
5266
* gpgconf:: Modify .gnupg home directories.
5267
* applygnupgdefaults:: Run gpgconf for all users.
5268
* gpgsm-gencert.sh:: Generate an X.509 certificate request.
5269
* gpg-preset-passphrase:: Put a passphrase into the cache.
5270
* gpg-connect-agent:: Communicate with a running agent.
5271
* gpgparsemail:: Parse a mail message into an annotated format
5272
* symcryptrun:: Call a simple symmetric encryption tool.
5273
5274
5275
File: gnupg.info, Node: watchgnupg, Next: gpgv, Up: Helper Tools
5276
5277
7.1 Read logs from a socket
5278
===========================
5279
5280
Most of the main utilities are able to write there log files to a Unix
5281
Domain socket if configured that way. `watchgnupg' is a simple
5282
listener for such a socket. It ameliorates the output with a time
5283
stamp and makes sure that long lines are not interspersed with log
5284
output from other utilities.
5285
5286
`watchgnupg' is commonly invoked as
5287
5288
watchgnupg --force ~/.gnupg/S.log
5289
5290
This starts it on the current terminal for listening on the socket
5291
`~/.gnupg/S.log'.
5292
5293
`watchgnupg' understands these options:
5294
5295
`--force'
5296
Delete an already existing socket file.
5297
5298
`--verbose'
5299
Enable extra informational output.
5300
5301
`--version'
5302
print version of the program and exit
5303
5304
`--help'
5305
Display a brief help page and exit
5306
5307
5308
5309
File: gnupg.info, Node: gpgv, Next: addgnupghome, Prev: watchgnupg, Up: Helper Tools
5310
5311
7.2 Verify OpenPGP signatures
5312
=============================
5313
5314
`gpgv2' is an OpenPGP signature verification tool.
5315
5316
This program is actually a stripped down version of `gpg' which is
5317
only able to check signatures. It is somewhat smaller than the fully
5318
blown `gpg' and uses a different (and simpler) way to check that the
5319
public keys used to make the signature are valid. There are no
5320
configuration files and only a few options are implemented.
5321
5322
`gpgv2' assumes that all keys in the keyring are trustworthy. By
5323
default it uses a keyring named `trustedkeys.gpg' which is assumed to
5324
be in the home directory as defined by GnuPG or set by an option or an
5325
environment variable. An option may be used to specify another keyring
5326
or even multiple keyrings.
5327
5328
5329
5330
`gpgv2' recognizes these options:
5331
5332
`--verbose'
5333
`-v'
5334
Gives more information during processing. If used twice, the input
5335
data is listed in detail.
5336
5337
`--quiet'
5338
`-q'
5339
Try to be as quiet as possible.
5340
5341
`--keyring FILE'
5342
Add FILE to the list of keyrings. If FILE begins with a tilde and
5343
a slash, these are replaced by the HOME directory. If the filename
5344
does not contain a slash, it is assumed to be in the
5345
home-directory ("~/.gnupg" if -homedir is not used).
5346
5347
`--status-fd N'
5348
Write special status strings to the file descriptor N. See the
5349
file DETAILS in the documentation for a listing of them.
5350
5351
`--logger-fd `n''
5352
Write log output to file descriptor `n' and not to stderr.
5353
5354
`--ignore-time-conflict'
5355
GnuPG normally checks that the timestamps associated with keys and
5356
signatures have plausible values. However, sometimes a signature
5357
seems to be older than the key due to clock problems. This option
5358
turns these checks into warnings.
5359
5360
`--homedir DIR'
5361
Set the name of the home directory to DIR. If his option is not
5362
used, the home directory defaults to `~/.gnupg'. It is only
5363
recognized when given on the command line. It also overrides any
5364
home directory stated through the environment variable `GNUPGHOME'
5365
or (on W32 systems) by means on the Registry entry
5366
HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
5367
5368
5369
The program returns 0 if everything was fine, 1 if at least one
5370
signature was bad, and other error codes for fatal errors.
5371
5372
7.2.1 Examples
5373
--------------
5374
5375
gpgv2 `pgpfile'
5376
gpgv2 `sigfile'
5377
Verify the signature of the file. The second form is used for
5378
detached signatures, where `sigfile' is the detached signature
5379
(either ASCII armored or binary) and are the signed data; if this
5380
is not given the name of the file holding the signed data is
5381
constructed by cutting off the extension (".asc", ".sig" or
5382
".sign") from `sigfile'.
5383
5384
5385
7.2.2 Environment
5386
-----------------
5387
5388
HOME
5389
Used to locate the default home directory.
5390
5391
GNUPGHOME
5392
If set directory used instead of "~/.gnupg".
5393
5394
5395
7.2.3 FILES
5396
-----------
5397
5398
~/.gnupg/trustedkeys.gpg
5399
The default keyring with the allowed keys
5400
5401
5402
`gpg2'(1)
5403
5404
5405
File: gnupg.info, Node: addgnupghome, Next: gpgconf, Prev: gpgv, Up: Helper Tools
5406
5407
7.3 Create .gnupg home directories.
5408
===================================
5409
5410
If GnuPG is installed on a system with existing user accounts, it is
5411
sometimes required to populate the GnuPG home directory with existing
5412
files. Especially a `trustlist.txt' and a keybox with some initial
5413
certificates are often desired. This scripts help to do this by
5414
copying all files from `/etc/skel/.gnupg' to the home directories of
5415
the accounts given on the command line. It takes care not to overwrite
5416
existing GnuPG home directories.
5417
5418
`addgnupghome' is invoked by root as:
5419
5420
addgnupghome account1 account2 ... accountn
5421
5422
5423
File: gnupg.info, Node: gpgconf, Next: applygnupgdefaults, Prev: addgnupghome, Up: Helper Tools
5424
5425
7.4 Modify .gnupg home directories.
5426
===================================
5427
5428
The `gpgconf' is a utility to automatically and reasonable safely query
5429
and modify configuration files in the `.gnupg' home directory. It is
5430
designed not to be invoked manually by the user, but automatically by
5431
graphical user interfaces (GUI).(1)
5432
5433
`gpgconf' provides access to the configuration of one or more
5434
components of the GnuPG system. These components correspond more or
5435
less to the programs that exist in the GnuPG framework, like GnuPG,
5436
GPGSM, DirMngr, etc. But this is not a strict one-to-one relationship.
5437
Not all configuration options are available through `gpgconf'.
5438
`gpgconf' provides a generic and abstract method to access the most
5439
important configuration options that can feasibly be controlled via
5440
such a mechanism.
5441
5442
`gpgconf' can be used to gather and change the options available in
5443
each component, and can also provide their default values. `gpgconf'
5444
will give detailed type information that can be used to restrict the
5445
user's input without making an attempt to commit the changes.
5446
5447
`gpgconf' provides the backend of a configuration editor. The
5448
configuration editor would usually be a graphical user interface
5449
program, that allows to display the current options, their default
5450
values, and allows the user to make changes to the options. These
5451
changes can then be made active with `gpgconf' again. Such a program
5452
that uses `gpgconf' in this way will be called GUI throughout this
5453
section.
5454
5455
* Menu:
5456
5457
* Invoking gpgconf:: List of all commands and options.
5458
* Format conventions:: Formatting conventions relevant for all commands.
5459
* Listing components:: List all gpgconf components.
5460
* Checking programs:: Check all programs know to gpgconf.
5461
* Listing options:: List all options of a component.
5462
* Changing options:: Changing options of a component.
5463
* Listing global options:: List all global options.
5464
* Files used by gpgconf:: What files are used by gpgconf.
5465
5466
---------- Footnotes ----------
5467
5468
(1) Please note that currently no locking is done, so concurrent
5469
access should be avoided. There are some precautions to avoid
5470
corruption with concurrent usage, but results may be inconsistent and
5471
some changes may get lost. The stateless design makes it difficult to
5472
provide more guarantees.
5473
5474
5475
File: gnupg.info, Node: Invoking gpgconf, Next: Format conventions, Up: gpgconf
5476
5477
7.4.1 Invoking gpgconf
5478
----------------------
5479
5480
One of the following commands must be given:
5481
5482
`--list-components'
5483
List all components. This is the default command used if none is
5484
specified.
5485
5486
`--check-programs'
5487
List all available backend programs and test whether they are
5488
runnable.
5489
5490
`--list-options COMPONENT'
5491
List all options of the component COMPONENT.
5492
5493
`--change-options COMPONENT'
5494
Change the options of the component COMPONENT.
5495
5496
`--apply-defaults'
5497
Update all configuration files with values taken from the global
5498
configuration file (usually `/etc/gnupg/gpgconf.conf').
5499
5500
`--list-config [FILENAME]'
5501
List the global configuration file in a colon separated format. If
5502
FILENAME is given, check that file instead.
5503
5504
`--check-config [FILENAME]'
5505
Run a syntax check on the global configuration file. If FILENAME
5506
is given, check that file instead.
5507
5508
5509
The following options may be used:
5510
5511
`-v'
5512
`--verbose'
5513
Outputs additional information while running. Specifically, this
5514
extends numerical field values by human-readable descriptions.
5515
5516
`-r'
5517
`--runtime'
5518
Only used together with `--change-options'. If one of the
5519
modified options can be changed in a running daemon process, signal
5520
the running daemon to ask it to reparse its configuration file
5521
after changing.
5522
5523
This means that the changes will take effect at run-time, as far as
5524
this is possible. Otherwise, they will take effect at the next
5525
start of the respective backend programs.
5526
5527
5528
5529
File: gnupg.info, Node: Format conventions, Next: Listing components, Prev: Invoking gpgconf, Up: gpgconf
5530
5531
7.4.2 Format conventions
5532
------------------------
5533
5534
Some lines in the output of `gpgconf' contain a list of colon-separated
5535
fields. The following conventions apply:
5536
5537
* The GUI program is required to strip off trailing newline and/or
5538
carriage return characters from the output.
5539
5540
* `gpgconf' will never leave out fields. If a certain version
5541
provides a certain field, this field will always be present in all
5542
`gpgconf' versions from that time on.
5543
5544
* Future versions of `gpgconf' might append fields to the list. New
5545
fields will always be separated from the previously last field by
5546
a colon separator. The GUI should be prepared to parse the last
5547
field it knows about up until a colon or end of line.
5548
5549
* Not all fields are defined under all conditions. You are required
5550
to ignore the content of undefined fields.
5551
5552
There are several standard types for the content of a field:
5553
5554
verbatim
5555
Some fields contain strings that are not escaped in any way. Such
5556
fields are described to be used _verbatim_. These fields will
5557
never contain a colon character (for obvious reasons). No
5558
de-escaping or other formatting is required to use the field
5559
content. This is for easy parsing of the output, when it is known
5560
that the content can never contain any special characters.
5561
5562
percent-escaped
5563
Some fields contain strings that are described to be
5564
_percent-escaped_. Such strings need to be de-escaped before
5565
their content can be presented to the user. A percent-escaped
5566
string is de-escaped by replacing all occurences of `%XY' by the
5567
byte that has the hexadecimal value `XY'. `X' and `Y' are from
5568
the set `0-9a-f'.
5569
5570
localised
5571
Some fields contain strings that are described to be _localised_.
5572
Such strings are translated to the active language and formatted in
5573
the active character set.
5574
5575
unsigned number
5576
Some fields contain an _unsigned number_. This number will always
5577
fit into a 32-bit unsigned integer variable. The number may be
5578
followed by a space, followed by a human readable description of
5579
that value (if the verbose option is used). You should ignore
5580
everything in the field that follows the number.
5581
5582
signed number
5583
Some fields contain a _signed number_. This number will always
5584
fit into a 32-bit signed integer variable. The number may be
5585
followed by a space, followed by a human readable description of
5586
that value (if the verbose option is used). You should ignore
5587
everything in the field that follows the number.
5588
5589
boolean value
5590
Some fields contain a _boolean value_. This is a number with
5591
either the value 0 or 1. The number may be followed by a space,
5592
followed by a human readable description of that value (if the
5593
verbose option is used). You should ignore everything in the
5594
field that follows the number; checking just the first character
5595
is sufficient in this case.
5596
5597
option
5598
Some fields contain an _option_ argument. The format of an option
5599
argument depends on the type of the option and on some flags:
5600
5601
no argument
5602
The simplest case is that the option does not take an
5603
argument at all (TYPE `0'). Then the option argument is an
5604
unsigned number that specifies how often the option occurs.
5605
If the `list' flag is not set, then the only valid number is
5606
`1'. Options that do not take an argument never have the
5607
`default' or `optional arg' flag set.
5608
5609
number
5610
If the option takes a number argument (ALT-TYPE is `2' or
5611
`3'), and it can only occur once (`list' flag is not set),
5612
then the option argument is either empty (only allowed if the
5613
argument is optional), or it is a number. A number is a
5614
string that begins with an optional minus character, followed
5615
by one or more digits. The number must fit into an integer
5616
variable (unsigned or signed, depending on ALT-TYPE).
5617
5618
number list
5619
If the option takes a number argument and it can occur more
5620
than once, then the option argument is either empty, or it is
5621
a comma-separated list of numbers as described above.
5622
5623
string
5624
If the option takes a string argument (ALT-TYPE is 1), and it
5625
can only occur once (`list' flag is not set) then the option
5626
argument is either empty (only allowed if the argument is
5627
optional), or it starts with a double quote character (`"')
5628
followed by a percent-escaped string that is the argument
5629
value. Note that there is only a leading double quote
5630
character, no trailing one. The double quote character is
5631
only needed to be able to differentiate between no value and
5632
the empty string as value.
5633
5634
string list
5635
If the option takes a number argument and it can occur more
5636
than once, then the option argument is either empty, or it is
5637
a comma-separated list of string arguments as described above.
5638
5639
The active language and character set are currently determined from
5640
the locale environment of the `gpgconf' program.
5641
5642
5643
File: gnupg.info, Node: Listing components, Next: Checking programs, Prev: Format conventions, Up: gpgconf
5644
5645
7.4.3 Listing components
5646
------------------------
5647
5648
The command `--list-components' will list all components that can be
5649
configured with `gpgconf'. Usually, one component will correspond to
5650
one GnuPG-related program and contain the options of that programs
5651
configuration file that can be modified using `gpgconf'. However, this
5652
is not necessarily the case. A component might also be a group of
5653
selected options from several programs, or contain entirely virtual
5654
options that have a special effect rather than changing exactly one
5655
option in one configuration file.
5656
5657
A component is a set of configuration options that semantically
5658
belong together. Furthermore, several changes to a component can be
5659
made in an atomic way with a single operation. The GUI could for
5660
example provide a menu with one entry for each component, or a window
5661
with one tabulator sheet per component.
5662
5663
The command argument `--list-components' lists all available
5664
components, one per line. The format of each line is:
5665
5666
`NAME:DESCRIPTION:PGMNAME:'
5667
5668
NAME
5669
This field contains a name tag of the component. The name tag is
5670
used to specify the component in all communication with `gpgconf'.
5671
The name tag is to be used _verbatim_. It is thus not in any
5672
escaped format.
5673
5674
DESCRIPTION
5675
The _string_ in this field contains a human-readable description
5676
of the component. It can be displayed to the user of the GUI for
5677
informational purposes. It is _percent-escaped_ and _localized_.
5678
5679
PGMNAME
5680
The _string_ in this field contains the absolute name of the
5681
program's file. It can be used to unambiguously invoke that
5682
program. It is _percent-escaped_.
5683
5684
Example:
5685
$ gpgconf --list-components
5686
gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
5687
gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
5688
scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
5689
gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
5690
dirmngr:Directory Manager:/usr/local/bin/dirmngr:
5691
5692
5693
File: gnupg.info, Node: Checking programs, Next: Listing options, Prev: Listing components, Up: gpgconf
5694
5695
7.4.4 Checking programs
5696
-----------------------
5697
5698
The command `--check-programs' is similar to `--list-components' but
5699
works on backend programs and not on components. It runs each program
5700
to test wether it is installed and runnable. This also includes a
5701
syntax check of all config file options of the program.
5702
5703
The command argument `--check-programs' lists all available
5704
programs, one per line. The format of each line is:
5705
5706
`NAME:DESCRIPTION:PGMNAME:AVAIL:OKAY:CFGFILE:LINE:ERROR:'
5707
5708
NAME
5709
This field contains a name tag of the program which is identical
5710
to the name of the component. The name tag is to be used
5711
_verbatim_. It is thus not in any escaped format. This field may
5712
be empty to indicate a continuation of error descriptions for the
5713
last name. The description and pgmname fields are then also empty.
5714
5715
DESCRIPTION
5716
The _string_ in this field contains a human-readable description
5717
of the component. It can be displayed to the user of the GUI for
5718
informational purposes. It is _percent-escaped_ and _localized_.
5719
5720
PGMNAME
5721
The _string_ in this field contains the absolute name of the
5722
program's file. It can be used to unambiguously invoke that
5723
program. It is _percent-escaped_.
5724
5725
AVAIL
5726
The _boolean value_ in this field indicates whether the program is
5727
installed and runnable.
5728
5729
OKAY
5730
The _boolean value_ in this field indicates whether the program's
5731
config file is syntactically okay.
5732
5733
CFGFILE
5734
If an error occured in the configuraion file (as indicated by a
5735
false value in the field `okay'), this field has the name of the
5736
failing configuration file. It is _percent-escaped_.
5737
5738
LINE
5739
If an error occured in the configuration file, this field has the
5740
line number of the failing statement in the configuration file.
5741
It is an _unsigned number_.
5742
5743
ERROR
5744
If an error occured in the configuration file, this field has the
5745
error text of the failing statement in the configuration file. It
5746
is _percent-escaped_ and _localized_.
5747
5748
5749
In the following example the `dirmngr' is not runnable and the
5750
configuration file of `scdaemon' is not okay.
5751
5752
$ gpgconf --check-programs
5753
gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
5754
gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
5755
scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
5756
gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
5757
dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
5758
5759
5760
File: gnupg.info, Node: Listing options, Next: Changing options, Prev: Checking programs, Up: gpgconf
5761
5762
7.4.5 Listing options
5763
---------------------
5764
5765
Every component contains one or more options. Options may be gathered
5766
into option groups to allow the GUI to give visual hints to the user
5767
about which options are related.
5768
5769
The command argument `--list-options COMPONENT' lists all options
5770
(and the groups they belong to) in the component COMPONENT, one per
5771
line. COMPONENT must be the string in the field NAME in the output of
5772
the `--list-components' command.
5773
5774
There is one line for each option and each group. First come all
5775
options that are not in any group. Then comes a line describing a
5776
group. Then come all options that belong into each group. Then comes
5777
the next group and so on. There does not need to be any group (and in
5778
this case the output will stop after the last non-grouped option).
5779
5780
The format of each line is:
5781
5782
`NAME:FLAGS:LEVEL:DESCRIPTION:TYPE:ALT-TYPE:ARGNAME:DEFAULT:ARGDEF:VALUE'
5783
5784
NAME
5785
This field contains a name tag for the group or option. The name
5786
tag is used to specify the group or option in all communication
5787
with `gpgconf'. The name tag is to be used _verbatim_. It is
5788
thus not in any escaped format.
5789
5790
FLAGS
5791
The flags field contains an _unsigned number_. Its value is the
5792
OR-wise combination of the following flag values:
5793
5794
`group (1)'
5795
If this flag is set, this is a line describing a group and
5796
not an option.
5797
5798
The following flag values are only defined for options (that is, if
5799
the `group' flag is not used).
5800
5801
`optional arg (2)'
5802
If this flag is set, the argument is optional. This is never
5803
set for TYPE `0' (none) options.
5804
5805
`list (4)'
5806
If this flag is set, the option can be given multiple times.
5807
5808
`runtime (8)'
5809
If this flag is set, the option can be changed at runtime.
5810
5811
`default (16)'
5812
If this flag is set, a default value is available.
5813
5814
`default desc (32)'
5815
If this flag is set, a (runtime) default is available. This
5816
and the `default' flag are mutually exclusive.
5817
5818
`no arg desc (64)'
5819
If this flag is set, and the `optional arg' flag is set, then
5820
the option has a special meaning if no argument is given.
5821
5822
`no change (128)'
5823
If this flag is set, gpgconf ignores requests to change the
5824
value. GUI frontends should grey out this option. Note,
5825
that manual changes of the configuration files are still
5826
possible.
5827
5828
LEVEL
5829
This field is defined for options and for groups. It contains an
5830
_unsigned number_ that specifies the expert level under which this
5831
group or option should be displayed. The following expert levels
5832
are defined for options (they have analogous meaning for groups):
5833
5834
`basic (0)'
5835
This option should always be offered to the user.
5836
5837
`advanced (1)'
5838
This option may be offered to advanced users.
5839
5840
`expert (2)'
5841
This option should only be offered to expert users.
5842
5843
`invisible (3)'
5844
This option should normally never be displayed, not even to
5845
expert users.
5846
5847
`internal (4)'
5848
This option is for internal use only. Ignore it.
5849
5850
The level of a group will always be the lowest level of all
5851
options it contains.
5852
5853
DESCRIPTION
5854
This field is defined for options and groups. The _string_ in
5855
this field contains a human-readable description of the option or
5856
group. It can be displayed to the user of the GUI for
5857
informational purposes. It is _percent-escaped_ and _localized_.
5858
5859
TYPE
5860
This field is only defined for options. It contains an _unsigned
5861
number_ that specifies the type of the option's argument, if any.
5862
The following types are defined:
5863
5864
Basic types:
5865
5866
`none (0)'
5867
No argument allowed.
5868
5869
`string (1)'
5870
An _unformatted string_.
5871
5872
`int32 (2)'
5873
A _signed number_.
5874
5875
`uint32 (3)'
5876
An _unsigned number_.
5877
5878
Complex types:
5879
5880
`pathname (32)'
5881
A _string_ that describes the pathname of a file. The file
5882
does not necessarily need to exist.
5883
5884
`ldap server (33)'
5885
A _string_ that describes an LDAP server in the format:
5886
5887
`HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN'
5888
5889
`key fingerprint (34)'
5890
A _string_ with a 40 digit fingerprint specifying a
5891
certificate.
5892
5893
`pub key (35)'
5894
A _string_ that describes a certificate by user ID, key ID or
5895
fingerprint.
5896
5897
`sec key (36)'
5898
A _string_ that describes a certificate with a key by user ID,
5899
key ID or fingerprint.
5900
5901
More types will be added in the future. Please see the ALT-TYPE
5902
field for information on how to cope with unknown types.
5903
5904
ALT-TYPE
5905
This field is identical to TYPE, except that only the types `0' to
5906
`31' are allowed. The GUI is expected to present the user the
5907
option in the format specified by TYPE. But if the argument type
5908
TYPE is not supported by the GUI, it can still display the option
5909
in the more generic basic type ALT-TYPE. The GUI must support all
5910
the defined basic types to be able to display all options. More
5911
basic types may be added in future versions. If the GUI
5912
encounters a basic type it doesn't support, it should report an
5913
error and abort the operation.
5914
5915
ARGNAME
5916
This field is only defined for options with an argument type TYPE
5917
that is not `0'. In this case it may contain a _percent-escaped_
5918
and _localised string_ that gives a short name for the argument.
5919
The field may also be empty, though, in which case a short name is
5920
not known.
5921
5922
DEFAULT
5923
This field is defined only for options for which the `default' or
5924
`default desc' flag is set. If the `default' flag is set, its
5925
format is that of an _option argument_ (*Note Format
5926
conventions::, for details). If the default value is empty, then
5927
no default is known. Otherwise, the value specifies the default
5928
value for this option. If the `default desc' flag is set, the
5929
field is either empty or contains a description of the effect if
5930
the option is not given.
5931
5932
ARGDEF
5933
This field is defined only for options for which the `optional
5934
arg' flag is set. If the `no arg desc' flag is not set, its
5935
format is that of an _option argument_ (*Note Format
5936
conventions::, for details). If the default value is empty, then
5937
no default is known. Otherwise, the value specifies the default
5938
argument for this option. If the `no arg desc' flag is set, the
5939
field is either empty or contains a description of the effect of
5940
this option if no argument is given.
5941
5942
VALUE
5943
This field is defined only for options. Its format is that of an
5944
_option argument_. If it is empty, then the option is not
5945
explicitely set in the current configuration, and the default
5946
applies (if any). Otherwise, it contains the current value of the
5947
option. Note that this field is also meaningful if the option
5948
itself does not take a real argument (in this case, it contains
5949
the number of times the option appears).
5950
5951
5952
File: gnupg.info, Node: Changing options, Next: Listing global options, Prev: Listing options, Up: gpgconf
5953
5954
7.4.6 Changing options
5955
----------------------
5956
5957
The command `--change-options COMPONENT' will attempt to change the
5958
options of the component COMPONENT to the specified values. COMPONENT
5959
must be the string in the field NAME in the output of the
5960
`--list-components' command. You have to provide the options that
5961
shall be changed in the following format on standard input:
5962
5963
`NAME:FLAGS:NEW-VALUE'
5964
5965
NAME
5966
This is the name of the option to change. NAME must be the string
5967
in the field NAME in the output of the `--list-options' command.
5968
5969
FLAGS
5970
The flags field contains an _unsigned number_. Its value is the
5971
OR-wise combination of the following flag values:
5972
5973
`default (16)'
5974
If this flag is set, the option is deleted and the default
5975
value is used instead (if applicable).
5976
5977
NEW-VALUE
5978
The new value for the option. This field is only defined if the
5979
`default' flag is not set. The format is that of an _option
5980
argument_. If it is empty (or the field is omitted), the default
5981
argument is used (only allowed if the argument is optional for this
5982
option). Otherwise, the option will be set to the specified value.
5983
5984
Examples:
5985
5986
To set the force option, which is of basic type `none (0)':
5987
5988
$ echo 'force:0:1' | gpgconf --change-options dirmngr
5989
5990
To delete the force option:
5991
5992
$ echo 'force:16:' | gpgconf --change-options dirmngr
5993
5994
The `--runtime' option can influence when the changes take effect.
5995
5996
5997
File: gnupg.info, Node: Listing global options, Next: Files used by gpgconf, Prev: Changing options, Up: gpgconf
5998
5999
7.4.7 Listing global options
6000
----------------------------
6001
6002
Sometimes it is useful for applications to look at the global options
6003
file `gpgconf.conf'. The colon separated listing format is record
6004
oriented and uses the first field to identify the record type:
6005
6006
`k'
6007
This describes a key record to start the definition of a new
6008
ruleset for a user/group. The format of a key record is:
6009
6010
`k:USER:GROUP:'
6011
6012
USER
6013
This is the user field of the key. It is percent escaped.
6014
See the definition of the gpgconf.conf format for details.
6015
6016
GROUP
6017
This is the group field of the key. It is percent escaped.
6018
6019
`r'
6020
This describes a rule record. All rule records up to the next key
6021
record make up a rule set for that key. The format of a rule
6022
record is:
6023
6024
`r:::COMPONENT:OPTION:FLAGS:VALUE:'
6025
6026
COMPONENT
6027
This is the component part of a rule. It is a plain string.
6028
6029
OPTION
6030
This is the option part of a rule. It is a plain string.
6031
6032
FLAG
6033
This is the flags part of a rule. There may be only one flag
6034
per rule but by using the same component and option, several
6035
flags may be assigned to an option. It is a plain string.
6036
6037
VALUE
6038
This is the optional value for the option. It is a percent
6039
escaped string with a single quotation mark to indicate a
6040
string. The quotation mark is only required to distinguish
6041
between no value specified and an empty string.
6042
6043
6044
Unknown record typs should be ignored. Note that there is intentionally
6045
no feature to change the global option file through `gpgconf'.
6046
6047
6048
File: gnupg.info, Node: Files used by gpgconf, Prev: Listing global options, Up: gpgconf
6049
6050
7.4.8 Files used by gpgconf
6051
---------------------------
6052
6053
`/etc/gnupg/gpgconf.conf'
6054
If this file exists, it is processed as a global configuration
6055
file. A commented example can be found in the `examples'
6056
directory of the distribution.
6057
6058
6059
File: gnupg.info, Node: applygnupgdefaults, Next: gpgsm-gencert.sh, Prev: gpgconf, Up: Helper Tools
6060
6061
7.5 Run gpgconf for all users.
6062
==============================
6063
6064
This script is a wrapper around `gpgconf' to run it with the command
6065
`--apply-defaults' for all real users with an existing GnuPG home
6066
directory. Admins might want to use this script to update he GnuPG
6067
configuration files for all users after `/etc/gnupg/gpgconf.conf' has
6068
been changed. This allows to enforce certain policies for all users.
6069
Note, that this is not a bulletproof of forcing a user to use certain
6070
options. A user may always directly edit the configuration files and
6071
bypass gpgconf.
6072
6073
`applygnupgdefaults' is invoked by root as:
6074
6075
applygnupgdefaults
6076
6077
6078
File: gnupg.info, Node: gpgsm-gencert.sh, Next: gpg-preset-passphrase, Prev: applygnupgdefaults, Up: Helper Tools
6079
6080
7.6 Generate an X.509 certificate request
6081
=========================================
6082
6083
This is a simple tool to interactivly generate a certificate request
6084
which will be printed to stdout.
6085
6086
`gpgsm-gencert.sh' is invoked as:
6087
6088
`gpgsm-cencert.sh'
6089
6090
6091
File: gnupg.info, Node: gpg-preset-passphrase, Next: gpg-connect-agent, Prev: gpgsm-gencert.sh, Up: Helper Tools
6092
6093
7.7 Put a passphrase into the cache.
6094
====================================
6095
6096
The `gpg-preset-passphrase' is a utility to seed the internal cache of
6097
a running `gpg-agent' with passphrases. It is mainly useful for
6098
unattended machines, where the usual `pinentry' tool may not be used
6099
and the passphrases for the to be used keys are given at machine
6100
startup.
6101
6102
Passphrases set with this utility don't expire unless the `--forget'
6103
option is used to explicitly clear them from the cache -- or
6104
`gpg-agent' is either restarted or reloaded (by sending a SIGHUP to
6105
it). It is necessary to allow this passphrase presetting by starting
6106
`gpg-agent' with the `--allow-preset-passphrase'.
6107
6108
* Menu:
6109
6110
* Invoking gpg-preset-passphrase:: List of all commands and options.
6111
6112
6113
File: gnupg.info, Node: Invoking gpg-preset-passphrase, Up: gpg-preset-passphrase
6114
6115
7.7.1 List of all commands and options.
6116
---------------------------------------
6117
6118
`gpg-preset-passphrase' is invoked this way:
6119
6120
gpg-preset-passphrase [options] [command] KEYGRIP
6121
6122
KEYGRIP is a 40 character string of hexadecimal characters
6123
identifying the key for which the passphrase should be set or cleared.
6124
This keygrip is listed along with the key when running the command:
6125
`gpgsm --dump-secret-keys'. One of the following command options must
6126
be given:
6127
6128
`--preset'
6129
Preset a passphrase. This is what you usually will use.
6130
`gpg-preset-passphrase' will then read the passphrase from `stdin'.
6131
6132
`--forget'
6133
Flush the passphrase for the given keygrip from the cache.
6134
6135
6136
The following additional options may be used:
6137
6138
`-v'
6139
`--verbose'
6140
Output additional information while running.
6141
6142
`-P STRING'
6143
`--passphrase STRING'
6144
Instead of reading the passphrase from `stdin', use the supplied
6145
STRING as passphrase. Note that this makes the passphrase visible
6146
for other users.
6147
6148
6149
File: gnupg.info, Node: gpg-connect-agent, Next: gpgparsemail, Prev: gpg-preset-passphrase, Up: Helper Tools
6150
6151
7.8 Communicate with a running agent.
6152
=====================================
6153
6154
The `gpg-connect-agent' is a utility to communicate with a running
6155
`gpg-agent'. It is useful to check out the commands gpg-agent provides
6156
using the Assuan interface. It might also be useful for scripting
6157
simple applications. Inputis expected at stdin and out put gets
6158
printed to stdout.
6159
6160
It is very similar to running `gpg-agent' in server mode; but here
6161
we connect to a running instance.
6162
6163
* Menu:
6164
6165
* Invoking gpg-connect-agent:: List of all options.
6166
* Controlling gpg-connect-agent:: Control commands.
6167
6168
6169
File: gnupg.info, Node: Invoking gpg-connect-agent, Next: Controlling gpg-connect-agent, Up: gpg-connect-agent
6170
6171
7.8.1 List of all options.
6172
--------------------------
6173
6174
`gpg-connect-agent' is invoked this way:
6175
6176
gpg-connect-agent [options]
6177
6178
The following options may be used:
6179
6180
`-v'
6181
`--verbose'
6182
Output additional information while running.
6183
6184
`-q'
6185
6186
`--quiet'
6187
Try to be as quiet as possible.
6188
6189
`--homedir DIR'
6190
Set the name of the home directory to DIR. If his option is not
6191
used, the home directory defaults to `~/.gnupg'. It is only
6192
recognized when given on the command line. It also overrides any
6193
home directory stated through the environment variable `GNUPGHOME'
6194
or (on W32 systems) by means on the Registry entry
6195
HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
6196
6197
`-S'
6198
`--raw-socket NAME'
6199
Connect to socket NAME assuming this is an Assuan style server.
6200
Do not run any special initializations or environment checks.
6201
This may be used to directly connect to any Assuan style socket
6202
server.
6203
6204
`-E'
6205
`--exec'
6206
Take the rest of the command line as a program and it's arguments
6207
and execute it as an assuan server. Here is how you would run
6208
`gpgsm':
6209
gpg-connect-agent --exec gpgsm --server
6210
6211
`--no-ext-connect'
6212
When using `-S' or `--exec', `gpg-connect-agent' connects to the
6213
assuan server in extended mode to allow descriptor passing. This
6214
option makes it use the old mode.
6215
6216
`--run FILE'
6217
Run the commands from FILE at startup and then continue with the
6218
regular input method.
6219
6220
`-s'
6221
`--subst'
6222
Run the command `/subst' at startup.
6223
6224
`--hex'
6225
Print data lines in a hex format and the ASCII representation of
6226
non-control characters.
6227
6228
`--decode'
6229
Decode data lines. That is to remove percent escapes but make
6230
sure that a new line always starts with a D and a space.
6231
6232
6233
6234
File: gnupg.info, Node: Controlling gpg-connect-agent, Prev: Invoking gpg-connect-agent, Up: gpg-connect-agent
6235
6236
7.8.2 Control commands.
6237
-----------------------
6238
6239
While reading Assuan commands, gpg-agent also allows a few special
6240
commands to control its operation. These control commands all start
6241
with a slash (`/').
6242
6243
`/echo ARGS'
6244
Just print ARGS.
6245
6246
`/let NAME VALUE'
6247
Set the variable NAME to VALUE. Variables are only substituted on
6248
the input if the `/subst' has been used. Variables are referenced
6249
by prefixing the name with a dollr sign and optionally include the
6250
name in curly braces. The rules for a valid name are idnetically
6251
to those of the standard bourne shell. This is not yet enforced
6252
but may be in the future. When used with curly braces no leading
6253
or trailing white space is allowed.
6254
6255
If a variable is not found, it is searched in the environment and
6256
if found copied to the table of variables.
6257
6258
Variable functions are available: The name of the function must be
6259
followed by at least one space and the at least one argument. The
6260
following functions are available:
6261
6262
`get'
6263
Return a value described by the argument. Available
6264
arguments are:
6265
6266
`cwd'
6267
The current working directory.
6268
6269
`homedir'
6270
The gnupg homedir.
6271
6272
`sysconfdir'
6273
GnuPG's system configuration directory.
6274
6275
`bindir'
6276
GnuPG's binary directory.
6277
6278
`libdir'
6279
GnuPG's library directory.
6280
6281
`libexecdir'
6282
GnuPG's library directory for executable files.
6283
6284
`datadir'
6285
GnuPG's data directory.
6286
6287
`serverpid'
6288
The PID of the current server. Command `/serverpid' must
6289
have been given to return a useful value.
6290
6291
`unescape ARGS'
6292
Remove C-style escapes from ARGS. Note that `\0' and `\x00'
6293
terminate the returned string implicitly. The string to be
6294
converted are the entire arguments right behind the
6295
delimiting space of the function name.
6296
6297
`unpercent ARGS'
6298
`unpercent+ ARGS'
6299
Remove percent style ecaping from ARGS. Note that `%00'
6300
terminates the string implicitly. The string to be converted
6301
are the entire arguments right behind the delimiting space of
6302
the function name. `unpercent+' also maps plus signs to a
6303
spaces.
6304
6305
`percent ARGS'
6306
`percent+ ARGS'
6307
Escape the ARGS using percent style ecaping. Tabs, formfeeds,
6308
linefeeds, carriage returns and colons are escaped.
6309
`percent+' also maps spaces to plus signs.
6310
6311
`errcode ARG'
6312
`errsource ARG'
6313
`errstring ARG'
6314
Assume ARG is an integer and evaluate it using `strtol'.
6315
Return the gpg-error error code, error source or a formatted
6316
string with the error code and error source.
6317
6318
`+'
6319
`-'
6320
`*'
6321
`/'
6322
`%'
6323
Evaluate all arguments as long integers using `strtol' and
6324
apply this operator. A division by zero yields an empty
6325
string.
6326
6327
`!'
6328
`|'
6329
`&'
6330
Evaluate all arguments as long integers using `strtol' and
6331
apply the logical oeprators NOT, OR or AND. The NOT operator
6332
works on the last argument only.
6333
6334
6335
`/definq NAME VAR'
6336
Use content of the variable VAR for inquiries with NAME. NAME may
6337
be an asterisk (`*') to match any inquiry.
6338
6339
`/definqfile NAME FILE'
6340
Use content of FILE for inquiries with NAME. NAME may be an
6341
asterisk (`*') to match any inquiry.
6342
6343
`/definqprog NAME PROG'
6344
Run PROG for inquiries matching NAME and pass the entire line to
6345
it as command line arguments.
6346
6347
`/showdef'
6348
Print all definitions
6349
6350
`/cleardef'
6351
Delete all definitions
6352
6353
`/sendfd FILE MODE'
6354
Open FILE in MODE (which needs to be a valid `fopen' mode string)
6355
and send the file descriptor to the server. This is usually
6356
followed by a command like `INPUT FD' to set the input source for
6357
other commands.
6358
6359
`/recvfd'
6360
Not yet implemented.
6361
6362
`/open VAR FILE [MODE]'
6363
Open FILE and assign the file descriptor to VAR. Warning: This
6364
command is experimental and might change in future versions.
6365
6366
`/close FD'
6367
Close the file descriptor FD. Warning: This command is
6368
experimental and might change in future versions.
6369
6370
`/showopen'
6371
Show a listy of open files.
6372
6373
`/serverpid'
6374
Send the Assuan command `GETINFO pid' to the server and store the
6375
returned PID for internal purposes.
6376
6377
`/sleep'
6378
Sleep for a second.
6379
6380
`/hex'
6381
`/nohex'
6382
Same as the command line option `--hex'.
6383
6384
`/decode'
6385
`/nodecode'
6386
Same as the command line option `--decode'.
6387
6388
`/subst'
6389
`/nosubst'
6390
Enable and disable variable substitution. It defaults to disabled
6391
unless the command line option `--subst' has been used. If /subst
6392
as been enabled once, leading whitespace is removed from input
6393
lines which makes scripts easier to read.
6394
6395
`/while CONDITION'
6396
`/end'
6397
These commands provide a way for executing loops. All lines
6398
between the `while' and the corresponding `end' are executed as
6399
long as the evaluation of CONDITION yields a non-zero value. The
6400
evaluation is done by passing CONDITION to the `strtol' function.
6401
Example:
6402
6403
/subst
6404
/let i 3
6405
/while $i
6406
/echo loop couter is $i
6407
/let i ${- $i 1}
6408
/end
6409
6410
`/run FILE'
6411
Run commands from FILE.
6412
6413
`/bye'
6414
Terminate the connection and the program
6415
6416
`/help'
6417
Print a list of available control commands.
6418
6419
6420
6421
File: gnupg.info, Node: gpgparsemail, Next: symcryptrun, Prev: gpg-connect-agent, Up: Helper Tools
6422
6423
7.9 Parse a mail message into an annotated format
6424
=================================================
6425
6426
The `gpgparsemail' is a utility currently only useful for debugging.
6427
Run it with `--help' for usage information.
6428
6429
6430
File: gnupg.info, Node: symcryptrun, Prev: gpgparsemail, Up: Helper Tools
6431
6432
7.10 Call a simple symmetric encryption tool.
6433
=============================================
6434
6435
Sometimes simple encryption tools are already in use for a long time and
6436
there might be a desire to integrate them into the GnuPG framework. The
6437
protocols and encryption methods might be non-standard or not even
6438
properly documented, so that a full-fledged encryption tool with an
6439
interface like gpg is not doable. `symcryptrun' provides a solution:
6440
It operates by calling the external encryption/decryption module and
6441
provides a passphrase for a key using the standard `pinentry' based
6442
mechanism through `gpg-agent'.
6443
6444
Note, that `symcryptrun' is only available if GnuPG has been
6445
configured with `--enable-symcryptrun' at build time.
6446
6447
* Menu:
6448
6449
* Invoking symcryptrun:: List of all commands and options.
6450
6451
6452
File: gnupg.info, Node: Invoking symcryptrun, Up: symcryptrun
6453
6454
7.10.1 List of all commands and options.
6455
----------------------------------------
6456
6457
`symcryptrun' is invoked this way:
6458
6459
symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE
6460
[--decrypt | --encrypt] [inputfile]
6461
6462
For encryption, the plain text must be provided on STDIN or as the
6463
argument INPUTFILE, and the ciphertext will be output to STDOUT. For
6464
decryption vice versa.
6465
6466
CLASS describes the calling conventions of the external tool.
6467
Currently it must be given as `confucius'. PROGRAM is the the full
6468
filename of that external tool.
6469
6470
For the class `confucius' the option `--keyfile' is required;
6471
KEYFILE is the name of a file containing the secret key, which may be
6472
protected by a passphrase. For detailed calling conventions, see the
6473
source code.
6474
6475
Note, that `gpg-agent' must be running before starting `symcryptrun'.
6476
6477
The following additional options may be used:
6478
6479
`-v'
6480
`--verbose'
6481
Output additional information while running.
6482
6483
`-q'
6484
6485
`--quiet'
6486
Try to be as quiet as possible.
6487
6488
`--homedir DIR'
6489
Set the name of the home directory to DIR. If his option is not
6490
used, the home directory defaults to `~/.gnupg'. It is only
6491
recognized when given on the command line. It also overrides any
6492
home directory stated through the environment variable `GNUPGHOME'
6493
or (on W32 systems) by means on the Registry entry
6494
HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
6495
6496
`--log-file FILE'
6497
Append all logging output to FILE. Default is to write logging
6498
informaton to STDERR.
6499
6500
6501
The possible exit status codes of `symcryptrun' are:
6502
6503
`0'
6504
Success.
6505
6506
`1'
6507
Some error occured.
6508
6509
`2'
6510
No valid passphrase was provided.
6511
6512
`3'
6513
The operation was canceled by the user.
6514
6515
6516
6517
File: gnupg.info, Node: Howtos, Next: System Notes, Prev: Helper Tools, Up: Top
6518
6519
8 How to do certain things
6520
**************************
6521
6522
This is a collection of small howto documents.
6523
6524
* Menu:
6525
6526
* Howto Create a Server Cert:: Creating a TLS server certificate.
6527
6528
6529
File: gnupg.info, Node: Howto Create a Server Cert, Up: Howtos
6530
6531
8.1 Creating a TLS server certificate
6532
=====================================
6533
6534
Here is a brief run up on how to create a server certificate. It has
6535
actually been done this way to get a certificate from CAcert to be used
6536
on a real server. It has only been tested with this CA, but there
6537
shouldn't be any problem to run this against any other CA.
6538
6539
Before you start, make sure that gpg-agent is running. As there is
6540
no need for a configuration file, you may simply enter:
6541
6542
$ gpgsm-gencert.sh >a.p10
6543
Key type
6544
[1] RSA
6545
[2] Existing key
6546
[3] Direct from card
6547
Your selection: 1
6548
You selected: RSA
6549
6550
I opted for creating a new RSA key. The other option is to use an
6551
already existing key, by selecting `2' and entering the so-called
6552
keygrip. Running the command `gpgsm --dump-secret-key USERID' shows
6553
you this keygrip. Using `3' offers another menu to create a
6554
certificate directly from a smart card based key.
6555
6556
Let's continue:
6557
6558
Key length
6559
[1] 1024
6560
[2] 2048
6561
Your selection: 1
6562
You selected: 1024
6563
6564
The script offers two common key sizes. With the current setup of
6565
CAcert, it does not make much sense to use a 2k key; their policies need
6566
to be revised anyway (a CA root key valid for 30 years is not really
6567
serious).
6568
6569
Key usage
6570
[1] sign, encrypt
6571
[2] sign
6572
[3] encrypt
6573
Your selection: 1
6574
You selected: sign, encrypt
6575
6576
We want to sign and encrypt using this key. This is just a suggestion
6577
and the CA may actually assign other key capabilities.
6578
6579
Now for some real data:
6580
6581
Name (DN)
6582
> CN=kerckhoffs.g10code.com
6583
6584
This is the most important value for a server certificate. Enter here
6585
the canonical name of your server machine. You may add other virtual
6586
server names later.
6587
6588
E-Mail addresses (end with an empty line)
6589
>
6590
6591
We don't need email addresses in a server certificate and CAcert
6592
would anyway ignore such a request. Thus just hit enter.
6593
6594
If you want to create a client certificate for email encryption, this
6595
would be the place to enter your mail address (e.g. <joe@example.org>).
6596
You may enter as many addresses as you like, however the CA may not
6597
accept them all or reject the entire request.
6598
6599
DNS Names (optional; end with an empty line)
6600
> www.g10code.com
6601
DNS Names (optional; end with an empty line)
6602
> ftp.g10code.com
6603
DNS Names (optional; end with an empty line)
6604
>
6605
6606
Here I entered the names of the servers which actually run on the
6607
machine given in the DN above. The browser will accept a certificate for
6608
any of these names. As usual the CA must approve all of these names.
6609
6610
URIs (optional; end with an empty line)
6611
>
6612
6613
It is possible to insert arbitrary URIs into a certificate; for a
6614
server certificate this does not make sense.
6615
6616
We have now entered all required information and `gpgsm' will
6617
display what it has gathered and ask whether to create the certificate
6618
request:
6619
6620
Parameters for certificate request to create:
6621
1 Key-Type: RSA
6622
2 Key-Length: 1024
6623
3 Key-Usage: sign, encrypt
6624
4 Name-DN: CN=kerckhoffs.g10code.com
6625
5 Name-DNS: www.g10code.com
6626
6 Name-DNS: ftp.g10code.com
6627
6628
Really create such a CSR?
6629
[1] yes
6630
[2] no
6631
Your selection: 1
6632
You selected: yes
6633
6634
`gpgsm' will now start working on creating the request. As this
6635
includes the creation of an RSA key it may take a while. During this
6636
time you will be asked 3 times for a passphrase to protect the created
6637
private key on your system. A pop up window will appear to ask for it.
6638
The first two prompts are for the new passphrase and for re-entering it;
6639
the third one is required to actually create the certificate signing
6640
request.
6641
6642
When it is ready, you should see the final notice:
6643
6644
gpgsm: certificate request created
6645
6646
Now, you may look at the created request:
6647
6648
$ cat a.p10
6649
-----BEGIN CERTIFICATE REQUEST-----
6650
MIIBnzCCAQgCAQAwITEfMB0GA1UEAxMWa2VyY2tob2Zmcy5nMTBjb2RlLmNvbTCB
6651
nzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA5h+uKRenpvbe+BnMY6siPO50LVyg
6652
HtB7kr+YISlPJ5JAFO12yQFz9Y0sBLHbjR+V+TOawwP1dZhGjlgnEBkMdWKuEBlS
6653
wFTALLX78GAyvAYAmPqSPDEYXkMECyUXVX/bbGI1bY8Y2OGy4w4D+v7e+xD2NBkm
6654
Bj5cNy+YMbGVldECAwEAAaA+MDwGCSqGSIb3DQEJDjEvMC0wKwYDVR0RBCQwIoIP
6655
d3d3LmcxMGNvZGUuY29tgg9mdHAuZzEwY29kZS5jb20wDQYJKoZIhvcNAQEFBQAD
6656
gYEAzBRIi8KTfKyebOlMtDN6oDYBOv+r9A4w3u/Z1ikjffaiN1Bmd2o9Ez9KXKHA
6657
IezLeSEA/rGUPN5Ur5qIJnRNQ8xrS+iLftr8msWQSZppVnA/vnqMrtqBUpitqAr0
6658
eYBmt1Uem2Y3UFABrKPglv2xzgGkrKX6AqmFoOnJWQ0QcTw=
6659
-----END CERTIFICATE REQUEST-----
6660
$
6661
6662
You may now proceed by logging into your account at the CAcert
6663
website, choose `Server Certificates - New', check `sign by class 3 root
6664
certificate', paste the above request block into the text field and
6665
click on `Submit'.
6666
6667
If everything works out fine, a certificate will be shown. Now run
6668
6669
$ gpgsm --import
6670
6671
and paste the certificate from the CAcert page into your terminal
6672
followed by a Ctrl-D
6673
6674
-----BEGIN CERTIFICATE-----
6675
MIIEIjCCAgqgAwIBAgIBTDANBgkqhkiG9w0BAQQFADBUMRQwEgYDVQQKEwtDQWNl
6676
cnQgSW5jLjEeMBwGA1UECxMVaHR0cDovL3d3dy5DQWNlcnQub3JnMRwwGgYDVQQD
6677
ExNDQWNlcnQgQ2xhc3MgMyBSb290MB4XDTA1MTAyODE2MjA1MVoXDTA3MTAyODE2
6678
MjA1MVowITEfMB0GA1UEAxMWa2VyY2tob2Zmcy5nMTBjb2RlLmNvbTCBnzANBgkq
6679
hkiG9w0BAQEFAAOBjQAwgYkCgYEA5h+uKRenpvbe+BnMY6siPO50LVygHtB7kr+Y
6680
ISlPJ5JAFO12yQFz9Y0sBLHbjR+V+TOawwP1dZhGjlgnEBkMdWKuEBlSwFTALLX7
6681
8GAyvAYAmPqSPDEYXkMECyUXVX/bbGI1bY8Y2OGy4w4D+v7e+xD2NBkmBj5cNy+Y
6682
MbGVldECAwEAAaOBtTCBsjAMBgNVHRMBAf8EAjAAMDQGA1UdJQQtMCsGCCsGAQUF
6683
BwMCBggrBgEFBQcDAQYJYIZIAYb4QgQBBgorBgEEAYI3CgMDMAsGA1UdDwQEAwIF
6684
oDAyBggrBgEFBQcBAQQmMCQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLmNhY2Vy
6685
dC5vcmcwKwYDVR0RBCQwIoIPd3d3LmcxMGNvZGUuY29tgg9mdHAuZzEwY29kZS5j
6686
b20wDQYJKoZIhvcNAQEEBQADggIBAAj5XAHCtzQR8PV6PkQBgZqUCbcfxGO/ZIp9
6687
aIT6J2z0Jo1OZI6KmConbqnZG9WyDlV5P7msQXW/Z9nBfoj4KSmNR8G/wtb8ClJn
6688
W8s75+K3ZLq1UgEyxBDrS7GjtbVaj7gsfZsuiQzxmk9lbl1gbkpJ3VEMjwVCTMlM
6689
fpjp8etyPhUZqOZaoKVaq//KTOsjhPMwz7TcfOkHvXketPrWTcefJQU7NKLH16D3
6690
mZAwnBxp3P51H6E6VG8AoJO8xCBuVwsbXKEf/FW+tmKG9pog6CaZQ9WibROTtnKj
6691
NJjSBsrUk5C+JowO/EyZRGm6R1tlok8iFXj+2aimyeBqDcxozNmFgh9F3S5u0wK0
6692
6cfYgkPVMHxgwV3f3Qh+tJkgLExN7KfO9hvpZqAh+CLQtxVmvpxEVEXKR6nwBI5U
6693
BaseulvVy3wUfg2daPkG17kDDBzQlsWC0BRF8anH+FWSrvseC3nS0a9g3sXF1Ic3
6694
gIqeAMhkant1Ac3RR6YCWtJKr2rcQNdDAxXK35/gUSQNCi9dclEzoOgjziuA1Mha
6695
94jYcvGKcwThn0iITVS5hOsCfaySBLxTzfIruLbPxXlpWuCW/6I/7YyivppKgEZU
6696
rUTFlNElRXCwIl0YcJkIaYYqWf7+A/aqYJCi8+51usZwMy3Jsq3hJ6MA3h1BgwZs
6697
Rtct3tIX
6698
-----END CERTIFICATE-----
6699
gpgsm: issuer certificate (#/CN=CAcert Class 3 Ro[...]) not found
6700
gpgsm: certificate imported
6701
6702
gpgsm: total number processed: 1
6703
gpgsm: imported: 1
6704
6705
gpgsm tells you that it has imported the certificate. It is now
6706
associated with the key you used when creating the request. The root
6707
certificate has not been found, so you may want to import it from the
6708
CACert website.
6709
6710
To see the content of your certificate, you may now enter:
6711
6712
$ gpgsm -K kerckhoffs.g10code.com
6713
/home/foo/.gnupg/pubring.kbx
6714
---------------------------
6715
Serial number: 4C
6716
Issuer: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.[...]
6717
Subject: /CN=kerckhoffs.g10code.com
6718
aka: (dns-name www.g10code.com)
6719
aka: (dns-name ftp.g10code.com)
6720
validity: 2005-10-28 16:20:51 through 2007-10-28 16:20:51
6721
key type: 1024 bit RSA
6722
key usage: digitalSignature keyEncipherment
6723
ext key usage: clientAuth (suggested), serverAuth (suggested), [...]
6724
fingerprint: 0F:9C:27:B2:DA:05:5F:CB:33:19:D8:E9:65:B9:BD:4F:B1:98:CC:57
6725
6726
I used `-K' above because this will only list certificates for which
6727
a private key is available. To see more details, you may use
6728
`--dump-secret-keys' instead of `-K'.
6729
6730
To make actual use of the certificate you need to install it on your
6731
server. Server software usally expects a PKCS\#12 file with key and
6732
certificate. To create such a file, run:
6733
6734
$ gpgsm --export-secret-key-p12 -a >kerckhoffs-cert.pem
6735
6736
You will be asked for the passphrase as well as for a new passphrase
6737
to be used to protect the PKCS\#12 file. The file now contains the
6738
certificate as well as the private key:
6739
6740
$ cat kerckhoffs-cert.pem
6741
Issuer ...: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.CA[...]
6742
Serial ...: 4C
6743
Subject ..: /CN=kerckhoffs.g10code.com
6744
aka ..: (dns-name www.g10code.com)
6745
aka ..: (dns-name ftp.g10code.com)
6746
6747
-----BEGIN PKCS12-----
6748
MIIHlwIBAzCCB5AGCSqGSIb37QdHAaCCB4EEggd9MIIHeTk1BJ8GCSqGSIb3DQEu
6749
[...many more lines...]
6750
-----END PKCS12-----
6751
$
6752
6753
Copy this file in a secure way to the server, install it there and
6754
delete the file then. You may export the file again at any time as long
6755
as it is available in GnuPG's private key database.
6756
6757
6758
File: gnupg.info, Node: System Notes, Next: Debugging, Prev: Howtos, Up: Top
6759
6760
9 Notes pertaining to certain OSes.
6761
***********************************
6762
6763
GnuPG has been developed on GNU/Linux systems and is know to work on
6764
almost all Free OSes. All modern POSIX systems should be supproted
6765
right now, however there are probably a lot of smaller glitches we need
6766
to fix first. The major problem areas are:
6767
6768
* For logging to sockets and other internal operations the
6769
`fopencookie' function (`funopen' under *BSD) is used. This is a
6770
very convient function which makes it possible to create outputs in
6771
a structures and easy maintainable way. The drawback however is
6772
that most proprietary OSes don't support this function. At
6773
g10 Code we have looked into several ways on how to overcome this
6774
limitation but no sufficiently easy and maintainable way has been
6775
found. Porting _glibc_ to a general POSIX system is of course an
6776
option and would make writing portable software much easier; this
6777
it has not yet been done and the system administrator wouldneed to
6778
cope with the GNU specific admin things in addition to the generic
6779
ones of his system.
6780
6781
We have now settled to use explicit stdio wrappers with a
6782
functionality similar to funopen. Although the code for this has
6783
already been written (_libestream_), we have not yet changed GnuPG
6784
to use it.
6785
6786
This means that on systems not supporting either `funopen' or
6787
`fopencookie', logging to a socket won't work, prompts are not
6788
formatted as pretty as theyshould be and `gpgsm''s `LISTKEYS'
6789
Assuan command does not work.
6790
6791
* We are planning to use file descriptor passing for interprocess
6792
communication. This will allow us save a lot of resources and
6793
improve performance of certain operations a lot. Systems not
6794
supporting this won't gain these benefits but we try to keep them
6795
working the satndard way as it is done today.
6796
6797
* We require more or less full POSIX compatibility. This has been
6798
arround for 15 years now and thus we don't believe it makes sense
6799
to support non POSIX systems anymore. Well, we of course the usual
6800
workarounds for near POSIX systems well be applied.
6801
6802
There is one exception of this rule: Systems based the Microsoft
6803
Windows API (called here _W32_) will be supported to some extend.
6804
6805
6806
* Menu:
6807
6808
* W32 Notes:: Microsoft Windows Notes
6809
6810
6811
File: gnupg.info, Node: W32 Notes, Up: System Notes
6812
6813
9.1 Microsoft Windows Notes
6814
===========================
6815
6816
The port to Microsoft Windows based OSes is pretty new and has some
6817
limitations we might remove over time. Note, that we have not yet done
6818
any security audit and you should not use any valuable private key. In
6819
particular, *using it on a box with more than one user, might lead to a
6820
key compromise*.
6821
6822
*It is quite possible that the current version does not even build.*
6823
6824
Current limitations are:
6825
6826
* The `LISTKEYS' Assuan command of `gpgsm' is not supported. Using
6827
the command line options `--list-keys' or `--list-secret-keys'
6828
does however work.
6829
6830
* No support for CRL checks. By default the option
6831
`--disable-crl-checks' has been turned on and the log will show an
6832
appropriate warning message. The reason for this is that the
6833
separate CRL checking daemin (`dirmngr') has not been ported to
6834
W32.
6835
6836
* `gpgconf' does not create backup files, so in case of trouble your
6837
configuration file might get lost.
6838
6839
* `watchgnupg' is not available. Logging to sockets is not possible.
6840
6841
* The periodical smartcard status checking done by `scdaemon' is not
6842
yet supported.
6843
6844
* Detached running of the gpg-agent is not directly supported. It
6845
needs to be started in a console and left alone then.
6846
6847
6848
6849
File: gnupg.info, Node: Debugging, Next: Copying, Prev: System Notes, Up: Top
6850
6851
10 How to solve problems
6852
************************
6853
6854
Everyone knows that software often does not do what it should do and
6855
thus there is a need to track down problems. We call this debugging in
6856
a reminiscent to the moth jamming a relay in a Mark II box back in 1947.
6857
6858
Most of the problems a merely configuration and user problems but
6859
nevertheless there are the most annoying ones and reponsible for many
6860
gray hairs. We try to give some guidelines here on how to identify and
6861
solve the problem at hand.
6862
6863
* Menu:
6864
6865
* Debugging Tools:: Description of some useful tools.
6866
* Debugging Hints:: Various hints on debugging.
6867
* Common Problems:: Commonly seen problems.
6868
* Architecture Details:: How the whole thing works internally.
6869
6870
6871
File: gnupg.info, Node: Debugging Tools, Next: Debugging Hints, Up: Debugging
6872
6873
10.1 Debugging Tools
6874
====================
6875
6876
The GnuPG distribution comes with a couple of tools, useful to help find
6877
and solving problems.
6878
6879
* Menu:
6880
6881
* kbxutil:: Scrutinizing a keybox file.
6882
6883
6884
File: gnupg.info, Node: kbxutil, Up: Debugging Tools
6885
6886
10.1.1 Scrutinizing a keybox file
6887
---------------------------------
6888
6889
A keybox is a file fomat used to store public keys along with meta
6890
information and indices. The commonly used one is the file
6891
`pubring.kbx' in the `.gnupg' directory. It contains all X.509
6892
certificates as well as OpenPGP keys(1) .
6893
6894
When called the standard way, e.g.:
6895
6896
`kbxutil ~/.gnupg/pubring.kbx'
6897
6898
it lists all records (called blobs) with there meta-information in a
6899
human readable format.
6900
6901
To see statistics on the keybox in question, run it using
6902
6903
`kbxutil --stats ~/.gnupg/pubring.kbx'
6904
6905
and you get an output like:
6906
6907
Total number of blobs: 99
6908
header: 1
6909
empty: 0
6910
openpgp: 0
6911
x509: 98
6912
non flagged: 81
6913
secret flagged: 0
6914
ephemeral flagged: 17
6915
6916
In this example you see that the keybox does not have any OpenPGP
6917
keys but contains 98 X.509 cerificates and a total of 17 keys or
6918
certificates are flagges as ephemeral, meaning that they are only
6919
temporary stored (cached) in the keybox and won't get listed using the
6920
usual commands provided by `gpgsm' or `gpg'. 81 certifcates are stored
6921
in a standard way and directly available from `gpgsm'.
6922
6923
To find duplicated certificates and keyblocks in a keybox file (this
6924
should not occur but sometimes things go wrong), run it using
6925
6926
`kbxutil --find-dups ~/.gnupg/pubring.kbx'
6927
6928
---------- Footnotes ----------
6929
6930
(1) Well, OpenPGP keys are not implemented, `gpg' still used the
6931
keyring file `pubring.gpg'
6932
6933
6934
File: gnupg.info, Node: Debugging Hints, Next: Common Problems, Prev: Debugging Tools, Up: Debugging
6935
6936
10.2 Various hints on debugging.
6937
================================
6938
6939
* How to find the IP address of a keyserver
6940
6941
If a round robin URL of is used for a keyserver (e.g.
6942
subkeys.gnupg.org); it is not easy to see what server is actually
6943
used. Using the keyserver debug option as in
6944
6945
gpg --keyserver-options debug=1 -v --refresh-key 1E42B367
6946
6947
is thus often helpful. Note that the actual output depends on the
6948
backend and may change from release to release.
6949
6950
6951
6952
File: gnupg.info, Node: Common Problems, Next: Architecture Details, Prev: Debugging Hints, Up: Debugging
6953
6954
10.3 Commonly Seen Problems
6955
===========================
6956
6957
* Error code `Not supported' from Dirmngr
6958
6959
Most likely the option `enable-ocsp' is active for gpgsm but
6960
Dirmngr's OCSP feature has not been enabled using `allow-ocsp' in
6961
`dirmngr.conf'.
6962
6963
* The Curses based Pinentry does not work
6964
6965
The far most common reason for this is that the environment
6966
variable `GPG_TTY' has not been set correctly. Make sure that it
6967
has been set to a real tty devce and not just to `/dev/tty'; i.e.
6968
`GPG_TTY=tty' is plainly wrong; what you want is `GPG_TTY=`tty`'
6969
-- note the back ticks. Also make sure that this environment
6970
variable gets exported, that is you should follow up the setting
6971
with an `export GPG_TTY' (assuming a Bourne style shell). Even for
6972
GUI based Pinentries; you should have set `GPG_TTY'. See the
6973
section on installing the `gpg-agent' on how to do it.
6974
6975
* SSH hangs while a popping up pinentry was expected
6976
6977
SSH has no way to tell the gpg-agent what terminal or X display it
6978
is running on. So when remotely logging into a box where a
6979
gpg-agent with SSH support is running, the pinentry will get
6980
popped up on whatever display t he gpg-agent has been started. To
6981
solve this problem you may issue the command
6982
6983
echo UPDATESTARTUPTTY | gpg-connect-agent
6984
6985
and the next pinentry will pop up on your display or screen.
6986
However, you need to kill the running pinentry first because only
6987
one pinentry may be running at once. If you plan to use ssh on a
6988
new display you should issue the above command before invoking ssh
6989
or any other service making use of ssh.
6990
6991
* Exporting a secret key without a certificate
6992
6993
I may happen that you have created a certificate request using
6994
`gpgsm' but not yet received and imported the certificate from the
6995
CA. However, you want to export the secret key to another machine
6996
right now to import the certificate over there then. You can do
6997
this with a little trick but it requires that you know the
6998
approximate time you created the signing request. By running the
6999
command
7000
7001
ls -ltr ~/.gnupg/private-keys-v1.d
7002
7003
you get a listing of all private keys under control of `gpg-agent'.
7004
Pick the key which best matches the creation time and run the
7005
command
7006
7007
/usr/local/libexec/gpg-protect-tool --p12-export ~/.gnupg/private-keys-v1.d/FOO >FOO.p12
7008
7009
(Please adjust the path to `gpg-protect-tool' to the approriate
7010
location). FOO is the name of the key file you picked (it should
7011
have the suffix `.key'). A Pinentry box will pop up and ask you
7012
for the current passphrase of the key and a new passphrase to
7013
protect it in the pkcs#12 file.
7014
7015
To import the created file on the machine you use this command:
7016
7017
/usr/local/libexec/gpg-protect-tool --p12-import --store FOO.p12
7018
7019
You will be asked for the pkcs#12 passphrase and a new passphrase
7020
to protect the imported private key at its new location.
7021
7022
Note that there is no easy way to match existing certificates with
7023
stored private keys because some private keys are used for Secure
7024
Shell or other purposes and don't have a corresponding certificate.
7025
7026
* A root certificate does not verify
7027
7028
A common problem is that the root certificate misses the required
7029
basicConstrains attribute and thus `gpgsm' rejects this
7030
certificate. An error message indicating "no value" is a sign for
7031
such a certificate. You may use the `relax' flag in
7032
`trustlist.txt' to accept the certificate anyway. Note that the
7033
fingerprint and this flag may only be added manually to
7034
`trustlist.txt'.
7035
7036
* Error message: "digest algorithm N has not been enabled"
7037
7038
The signature is broken. You may try the option
7039
`--extra-digest-algo SHA256' to workaround the problem. The
7040
number N is the internal algorighm indentifier; for example 8
7041
refers to SHA-256.
7042
7043
7044
7045
File: gnupg.info, Node: Architecture Details, Prev: Common Problems, Up: Debugging
7046
7047
10.4 How the whole thing works internally.
7048
==========================================
7049
7050
* Menu:
7051
7052
* GnuPG-1 and GnuPG-2:: Relationship between the two branches.
7053
7054
7055
File: gnupg.info, Node: GnuPG-1 and GnuPG-2, Up: Architecture Details
7056
7057
10.4.1 Relationship between the two branches.
7058
---------------------------------------------
7059
7060
Here is a little picture showing how the components work together:
7061
7062
[image src="gnupg-card-architecture.png" ]
7063
7064
Lets try to explain it:
7065
7066
TO BE DONE.
7067
Loggerhead is a web-based interface for Breezy
Version: 2.0.1