52
59
If everything succeeds, you have a working GnuPG with support for
53
60
S/MIME and smartcards. Note that there is no binary gpg but a gpg2 so
54
that this package won't confict with a GnuPG 1.2 or 1.3
55
installation. gpg2 behaves just like gpg; it is however suggested to
56
keep using gpg 1.2.x or 1.3.x. gpg2 is not even build by default.
61
that this package won't conflict with a GnuPG 1.4 installation. gpg2
62
behaves just like gpg.
58
In case of problem please ask on gpa-dev@gnupg.org for advise. Note
64
In case of problem please ask on gnupg-users@gnupg.org for advise. Note
59
65
that this release is only expected to build on GNU and *BSD systems.
61
A texinfo manual named `gnupg.info' will get installed. Some commands
62
and options given below. See also the section `SMARTCARD INTRO'.
68
See the info documentation ("info gnupg") for a full list of commands
76
Read information about the private keys from the smartcard and
77
import the certificates from there.
81
Export all certificates stored in the Keybox or those specified on
82
the command line. When using --armor a few informational lines are
83
prepended before each block.
94
Using N of -2 includes all certificate except for the Root cert,
95
-1 includes all certs, 0 does not include any certs, 1 includes only
96
the signers cert (this is the default) and all other positives
97
values include up to N certs starting with the signer cert.
99
--policy-file <filename>
101
Chnage the deault name of the policy file
103
--enable-policy-checks
104
--disable-policy-checks
106
By default policy checks are enabled. These options may be used to
112
By default the CRL checks are enabled and the DirMngr is used to
113
check for revoked certificates. The disable option is most useful
114
with a off-line connection to suppres this check.
116
--agent-program <path_to_agent_program>
118
Specify an agent program to be used for secret key operations. The
119
default value is "../agent/gpg-agent". This is only used as a
120
fallback when the envrionment varaibale GPG_AGENT_INFO is not set or
121
a running agent can't be connected.
123
--dirmngr-program <path_to_dirmgr_program>
125
Specify a dirmngr program to be used for CRL checks. The default
126
value is "/usr/sbin/dirmngr". This is only used as a fallback when
127
the environment varaibale DIRMNGR_INFO is not set or a running
128
dirmngr can't be connected.
132
Don't print the warning "no secure memory"
136
Create PEM ecoded output. Default is binary output.
140
Create Base-64 encoded output; i.e. PEM without the header lines.
144
Assume the input data is PEM encoded. Default is to autodetect the
145
encoding but this is may fail.
149
Assume the input data is plain base-64 encoded.
153
Assume the input data is binary encoded.
157
Run in server mode. This is used by GPGME to control gpgsm. See
158
the assuan specification regarding gpgsm about the used protocol.
159
Some options are ignored in server mode.
161
--local-user <user_id>
163
Set the user to be used for signing. The default is the first
164
secret key found in the database.
168
Displays extra information with the --list-keys commands. Especially
169
a line tagged "grp" is printed which tells you the keygrip of a
170
key. This is string is for example used as the filename of the
178
--pinentry-program <path_to_pinentry_program>
180
Specify the PINentry program. The default value is
181
"<prefix>/bin/pinentry" so you most likely want to specify it.
185
Tell the pinentry not to grab keybourd and mouse. You most likely
186
want to give this option during testing and development to avoid
187
lockups in case of bugs.
193
--ctapi-driver <libraryname>
195
The default for Scdaemon is to use the PC/SC API currently provided
196
by libpcsclite.so. As an alternative the ctAPI can be used by
197
specify this option with the appropriate driver name
198
(e.g. libtowitoko.so).
200
--reader-port <portname>
202
This specifies the port of the chipcard reader. For PC/SC this is
203
currently ignored and the first PC/SC reader is used. For the
204
ctAPI, a number must be specified (the default is 32768 for the
209
Disable the integrated support for CCID compliant readers. This
210
allows to fall back to one of the other drivers even if the internal
211
CCID driver can handle the reader. Note, that CCID support is only
212
available if libusb was available at build time.
218
The default home directory is ~/.gnupg. It can be changed by
219
either the --homedir option or by seting the environment variable
220
GNUPGHOME. This is a list of files usually found in this directory:
224
Options for gpgsm. Options are the same as the command line
225
options but don't enter the leading dashes and give arguments
226
without an equal sign. Blank lines and lines starting with a
227
hash mark as the first non whitye space character are ignored.
231
Options for gpg-agent
235
Options for scdaemon.
239
Options for the DirMngr which is not part of this package and
240
the option file wilol most likely be moved to /etc
244
Options for gpg. Note that old versions of gpg use the
245
filename `options' instead of `gpg.conf'.
249
Options for gpg; tried before gpg.conf
254
A list of allowed CA policies. This file should give the
255
object identifiers of the policies line by line. Empty lines
256
and lines startung with a hash mark are ignored.
264
A list of trusted certificates. The file will be created
265
automagically with some explaining comments. By using
266
gpg-agent's option --allow-mark-trusted, gpg-agent may add new
267
entries after user confirmation.
271
Used internally for keeping the state of the RNG over
276
The database file with the certificates.
280
The database file with the OpenPGP public keys. This will
281
eventually be merged with pubring.kbx
285
The database file with the OpenPGP secret keys. This will be
286
removed when gpg is changed to make use of the gpg-agent.
291
Directory holding the private keys maintained by gpg-agent.
292
For detailed info see agent/keyformat.txt. Note that there is
293
a helper tool gpg-protect-tool which may be used to protect or
294
unprotect keys. This is however nothing a user should care
301
Here is a list of directories with source files:
303
jnlib/ utility functions
305
g10/ the gpg program here called gpg2
306
sm/ the gpgsm program
308
scd/ the smartcard daemon
313
HOW TO SPECIFY A USER ID
314
========================
316
Due to the way X.509 certificates are made up we need a few new ways
317
to specify a certificate (aka key in OpenPGP). In addition to the
318
ways a user ID can be specified with gpg, I have implemented 3 new
319
modes for gpgsm, here is the entire list of ways to specify a key:
323
This format is deducded from the length of the string and its
324
content or "0x" prefix. For use with OpenPGP a exclamation mark may
325
be appended to force use of the specified (sub)key.
327
As with v34 OpenPGP keys, the keyID of an X509 certificate are the
328
low 64 bits of the SHA-1 fingerprint. The use of keyIDs is just a
329
shortcut, for all automated processing the fingerprint should be
346
This is format is deduced from the length of the string and its
347
content or "0x" prefix. Note, that only the 20 byte fingerprint is
348
used with GPGSM (SHA-1 hash of the certificate). For use with
349
OpenPGP a exclamation mark may be appended to force use of the
354
1234343434343434C434343434343434
355
123434343434343C3434343434343734349A3434
356
0E12343434343434343434EAB3484343434343434
357
0xE12343434343434343434EAB3484343434343434
359
* Exact match on OpenPGP user ID
361
This is denoted by a leading equal sign. It does not make much
366
=Heinrich Heine <heinrichh@uni-duesseldorf.de>
368
* Exact match on an email address.
370
This is indicated by enclosing the email address in the usual way
371
with left and right angles
375
<heinrichh@uni-duesseldorf.de>
379
All words must match exactly (not case sensitive) but can appear in
380
any order in the user ID or a subjects name. Words are any
381
sequences of letters, digits, the underscore and all characters
386
+Heinrich Heine duesseldorf
388
* Exact match by subject's DN
390
This is indicated by a leading slash, directly followed by the
391
rfc2253 encoded DN of the subject. Note that you can't use the
392
string printed by "gpgsm --list-keys" because that one as been
393
reordered and modified for better readability; use --with-colons to
394
print the raw (but standard escaped) rfc2253 string
398
/CN=Heinrich Heine,O=Poets,L=Paris,C=FR
400
* Excact match by issuer's DN
402
This is indicated by a leading hash mark, directly followed by a
403
slash and then directly followed by the rfc2253 encoded DN of the
404
issuer. This should return the Root cert of the issuer. See note
409
#/CN=Root Cert,O=Poets,L=Paris,C=FR
411
* Exact match by serial number and issuer's DN
413
This is indicated by a hash mark, followed by the hexadecmal
414
representation of the serial number, the followed by a slash and
415
the RFC2253 encoded DN of the issuer. See note above.
419
#4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
423
By case insensitive substring matching. This is the default mode
424
but applications may want to explicitly indicate this by putting
425
the asterisk in front.
433
Please note that we have reused the hash mark identifier which was
434
used in old GnuPG versions to indicate the so called local-id. It is
435
not anymore used and there should be no conflict when used with X.509
438
Using the rfc2253 format of DNs has the drawback that it is not
439
possible to map them back to the original encoding, however we don't
440
have to do this, because our key database stores this encoding as meta
443
Some of the search modes are not yet implemented ;-)
446
HOW TO IMPORT A PRIVATE KEY
447
===========================
448
There is some limited support to import a private key from a PKCS-12
451
gpgsm --import foo.p12
453
This requires that the gpg-agent is running.
456
HOW TO EXPORT A PRIVATE KEY
457
===========================
458
There is also limited support to export a private key in PKCS-12
459
format. However there is no MAC applied.
461
gpgsm --export-secret-key-p12 userID >foo.p12
467
GPG, the OpenPGP part of GnuPG, supports the OpenPGP smartcard
468
(surprise!); see http://g10code.com/p-card.html and
469
http://www.gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
471
GPGSM, the CMS (S/MIME) part of GnuPG, supports two kinds of
472
smartcards. The most flexible way is to use PKCS#15 compliant cards,
473
however you must have build GnuPG with support for the OpenSC library.
474
The build process automagically detects the presence of this library
475
and will include support for these cards.
477
The other cards we currently support are the Telesec NetKey card with
478
the NKS 2.0 card application and all generic DINSIG cards.
480
Before GPGSM can make use of a new card it must gather some
481
information, like the card's serial number, the public keys and the
482
certificates stored on the card. Thus for a new card you need to run
487
once. This is also a good test to see whether your card reader is
488
properly installed. See below in case of error. Once this has been
489
done you may use the keys stored on the card in the same way you use
490
keys stored on the disk. gpgsm automagically knows whether a card is
491
required and will pop up the pinentry to ask you to insert the
494
For selecting the driver, see the options of scdaemon. A useful
495
debugging flag is "--debug 2048" showing the communication between
496
scdaemon and the reader.
67
Note that the PKITS tests are always skipped unless you copy the PKITS
68
test data file into the tests/pkits directory.
74
The complete documentation is in the texinfo manual named
75
`gnupg.info'. Run "info gnupg" to read it. If you want a a printable
76
copy of the manual, change to the "doc" directory and enter "make pdf"
77
For a HTML version enter "make html" and point your browser to
78
gnupg.html/index.html. Standard man pages for all components are
79
provided as well. An online version of the manual is available at
80
http://www.gnupg.org/documentation/manuals/gnupg/ . A version of the
81
manual pertaining to the current development snapshot is at
82
http://www.gnupg.org/documentation/manuals/gnupg-devel/ .
85
GNUPG 1.4 AND GNUPG 2.0
86
=======================
88
GnuPG 2.0 is a newer version of GnuPG with additional support for
89
S/MIME. It has a different design philosophy that splits
90
functionality up into several modules. Both versions may be installed
91
simultaneously without any conflict (gpg is called gpg2 in GnuPG 2).
92
In fact, the gpg version from GnuPG 1.4 is able to make use of the
93
gpg-agent as included in GnuPG 2 and allows for seamless passphrase
94
caching. The advantage of GnuPG 1.4 is its smaller size and no
95
dependency on other modules at run and build time.
98
HOW TO GET MORE INFORMATION
99
===========================
101
The primary WWW page is "http://www.gnupg.org"
102
The primary FTP site is "ftp://ftp.gnupg.org/gcrypt/"
104
See http://www.gnupg.org/download/mirrors.html for a list of mirrors
105
and use them if possible. You may also find GnuPG mirrored on some of
106
the regular GNU mirrors.
108
We have some mailing lists dedicated to GnuPG:
110
gnupg-announce@gnupg.org For important announcements like new
111
versions and such stuff. This is a
112
moderated list and has very low traffic.
113
Do not post to this list.
115
gnupg-users@gnupg.org For general user discussion and
118
gnupg-de@gnupg.org German speaking counterpart of
121
gnupg-ru@gnupg.org Russian speaking counterpart of
124
gnupg-devel@gnupg.org GnuPG developers main forum.
126
You subscribe to one of the list by sending mail with a subject of
127
"subscribe" to x-request@gnupg.org, where x is the name of the mailing
128
list (gnupg-announce, gnupg-users, etc.). An archive of the mailing
129
lists are available at http://www.gnupg.org/documentation/mailing-lists.html
131
Please direct bug reports to http://bugs.gnupg.org or post them direct
132
to the mailing list <gnupg-devel@gnupg.org>.
134
Please direct questions about GnuPG to the users mailing list or one
135
of the pgp newsgroups; please do not direct questions to one of the
136
authors directly as we are busy working on improvements and bug fixes.
137
The English and German mailing lists are watched by the authors and we
138
try to answer questions when time allows us to do so.
140
Commercial grade support for GnuPG is available; please see
141
http://www.gnupg.org/service.html .
144
This file is Free Software; as a special exception the authors gives
145
unlimited permission to copy and/or distribute it, with or without
146
modifications, as long as this notice is preserved. For conditions
147
of the whole package, please see the file COPYING. This file is
148
distributed in the hope that it will be useful, but WITHOUT ANY
149
WARRANTY, to the extent permitted by law; without even the implied
150
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
added
removed
README
