gpg: Rework ECC support and add experimental support for Ed25519.
[gnupg.git] / README
1                        The GNU Privacy Guard 2
2                       =========================
3                              Version 2.1
4
5    THIS IS A DEVELOPMENT VERSION AND NOT INTENDED FOR REGULAR USE.
6
7       Copyright 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
8                 2006, 2007, 2008, 2009, 2010, 2011, 2012,
9                 2013 Free Software Foundation, Inc.
10
11
12 INTRODUCTION
13 ============
14
15 GnuPG is GNU's tool for secure communication and data storage.  It can
16 be used to encrypt data and to create digital signatures.  It includes
17 an advanced key management facility and is compliant with the proposed
18 OpenPGP Internet standard as described in RFC4880 and the S/MIME
19 standard as described by several RFCs.
20
21 GnuPG is distributed under the terms of the GNU General Public
22 License.  See the file COPYING for details.  GnuPG works best on
23 GNU/Linux or *BSD systems.  Most other Unices are also supported but
24 are not as well tested as the Free Unices.
25
26 GnuPG 2.0 is the stable version of GnuPG integrating support for
27 OpenPGP and S/MIME.  It does not conflict with an installed 1.4
28 OpenPGP-only version.
29
30
31 BUILD INSTRUCTIONS
32 ==================
33
34 GnuPG 2.1 depends on the following packages:
35
36   npth         (ftp://ftp.gnupg.org/gcrypt/npth/)
37   libgpg-error (ftp://ftp.gnupg.org/gcrypt/libgpg-error/)
38   libgcrypt    (ftp://ftp.gnupg.org/gcrypt/libgcrypt/)
39   libksba      (ftp://ftp.gnupg.org/gcrypt/libksba/)
40   libassuan    (ftp://ftp.gnupg.org/gcrypt/libassuan/)
41
42 You should get the latest versions of course, the GnuPG configure
43 script complains if a version is not sufficient.
44
45 You also need the Pinentry package for most functions of GnuPG;
46 however it is not a build requirement.  Pinentry is available at
47 ftp://ftp.gnupg.org/gcrypt/pinentry/ .
48
49 After building and installing the above packages in the order as given
50 above, you may continue with GnuPG installation (you may also just try
51 to build GnuPG to see whether your already installed versions are
52 sufficient).
53
54 As with all packages, you just have to do
55
56  ./configure
57  make
58  make install
59
60 (Before doing install you might need to become root.)
61
62 If everything succeeds, you have a working GnuPG with support for
63 S/MIME and smartcards.  Note that there is no binary gpg but a gpg2 so
64 that this package won't conflict with a GnuPG 1.4 installation.  gpg2
65 behaves just like gpg.
66
67 In case of problem please ask on gnupg-users@gnupg.org mailing list
68 for advise.
69
70 Note that the PKITS tests are always skipped unless you copy the PKITS
71 test data file into the tests/pkits directory.  There is no need to
72 run these test and some of them may even fail because the test scripts
73 are not yet complete.
74
75 You may run
76
77   gpgconf --list-dirs
78
79 to view the default directories used by GnuPG.
80
81
82 MIGRATION FROM 1.4 or 2.0 to 2.1
83 ================================
84
85 The major change in 2.1 is gpg-agent taking care of the OpenPGP secret
86 keys (those managed by GPG).  The former file "secring.gpg" will not
87 be used anymore.  Newly generated keys are stored in the agent's key
88 store directory "~/.gnupg/private-keys-v1.d/".
89
90 To migrate your existing keys you need to run the command
91
92   gpg2 --batch --import ~/.gnupg/secring.gpg
93
94 Secret keys already imported are skipped by this command.  It is
95 advisable to keep the secring.gpg for use with older versions of GPG.
96
97 The use of "--batch" with "--import" is highly recommended.  If you do
98 not use "--batch" the agent would ask for the passphrase of each key.
99 In this case you may use the Cancel button of the Pinentry to skip
100 importing this key.  If you want to stop the enite import process and
101 you use a decent version of Pinentry, you should close the Pinentry
102 window instead of hitting the Cancel button.
103
104 Note that gpg-agent now uses a fixed socket by default.  All tools
105 will start the gpg-agent as needed.  In general there is no more need
106 to set the GPG_AGENT_INFO environment variable.  The SSH_AUTH_SOCK
107 environment variable should be set to a fixed value.
108
109 GPG's smartcard commands --card-edit and --card-status as well as some
110 of the card related sub-commands of --edit-key are not yet fully
111 supported.  However, signing and decryption with a smartcard does
112 work.
113
114 The Dirmngr is now part of GnuPG proper.  Thus there is no more need
115 to install the separate dirmngr package.  The directroy layout of
116 Dirmngr changed to make use of the GnuPG directories; for example you
117 use /etc/gnupg/trusted-certs and /var/lib/gnupg/extra-certs.  Dirmngr
118 needs to be started as a system daemon.
119
120
121
122 DOCUMENTATION
123 =============
124
125 The complete documentation is in the texinfo manual named
126 `gnupg.info'.  Run "info gnupg" to read it.  If you want a a printable
127 copy of the manual, change to the "doc" directory and enter "make pdf"
128 For a HTML version enter "make html" and point your browser to
129 gnupg.html/index.html.  Standard man pages for all components are
130 provided as well.  An online version of the manual is available at
131 http://www.gnupg.org/documentation/manuals/gnupg/ .  A version of the
132 manual pertaining to the current development snapshot is at
133 http://www.gnupg.org/documentation/manuals/gnupg-devel/ .
134
135
136 GNUPG 1.4 AND GNUPG 2.0
137 =======================
138
139 GnuPG 2.0 is a newer version of GnuPG with additional support for
140 S/MIME.  It has a different design philosophy that splits
141 functionality up into several modules.  Both versions may be installed
142 simultaneously without any conflict (gpg is called gpg2 in GnuPG 2).
143 In fact, the gpg version from GnuPG 1.4 is able to make use of the
144 gpg-agent as included in GnuPG 2 and allows for seamless passphrase
145 caching.  The advantage of GnuPG 1.4 is its smaller size and no
146 dependency on other modules at run and build time.
147
148
149 HOW TO GET MORE INFORMATION
150 ===========================
151
152 The primary WWW page is "http://www.gnupg.org"
153 The primary FTP site is "ftp://ftp.gnupg.org/gcrypt/"
154
155 See http://www.gnupg.org/download/mirrors.html for a list of mirrors
156 and use them if possible.  You may also find GnuPG mirrored on some of
157 the regular GNU mirrors.
158
159 We have some mailing lists dedicated to GnuPG:
160
161    gnupg-announce@gnupg.org   For important announcements like new
162                               versions and such stuff.  This is a
163                               moderated list and has very low traffic.
164                               Do not post to this list.
165
166    gnupg-users@gnupg.org      For general user discussion and
167                               help (English).
168
169    gnupg-de@gnupg.org         German speaking counterpart of
170                               gnupg-users.
171
172    gnupg-ru@gnupg.org         Russian speaking counterpart of
173                               gnupg-users.
174
175    gnupg-devel@gnupg.org      GnuPG developers main forum.
176
177 You subscribe to one of the list by sending mail with a subject of
178 "subscribe" to x-request@gnupg.org, where x is the name of the mailing
179 list (gnupg-announce, gnupg-users, etc.).  An archive of the mailing
180 lists are available at http://www.gnupg.org/documentation/mailing-lists.html
181
182 Please direct bug reports to http://bugs.gnupg.org or post them direct
183 to the mailing list <gnupg-devel@gnupg.org>.
184
185 Please direct questions about GnuPG to the users mailing list or one
186 of the pgp newsgroups; please do not direct questions to one of the
187 authors directly as we are busy working on improvements and bug fixes.
188 The English and German mailing lists are watched by the authors and we
189 try to answer questions when time allows us to do so.
190
191 Commercial grade support for GnuPG is available; for a listing of
192 offers see http://www.gnupg.org/service.html .  The driving force
193 behind the development of GnuPG is the company of its principal
194 author, Werner Koch.  Maintenance and improvement of GnuPG and related
195 software takes up most of their resources.  To allow him to continue
196 his work he asks to either purchase a support contract, engage them
197 for custom enhancements, or to donate money.  See http://g10code.com .
198
199
200   This file is Free Software; as a special exception the authors gives
201   unlimited permission to copy and/or distribute it, with or without
202   modifications, as long as this notice is preserved. For conditions
203   of the whole package, please see the file COPYING.  This file is
204   distributed in the hope that it will be useful, but WITHOUT ANY
205   WARRANTY, to the extent permitted by law; without even the implied
206   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.