Release 1.4.2.
[gpgme.git] / README
1                   GPGME - GnuPG Made Easy
2                 ---------------------------
3
4          Copyright 2004, 2006, 2010, 2012, 2013 g10 Code GmbH
5
6 This file is free software; as a special exception the author gives
7 unlimited permission to copy and/or distribute it, with or without
8 modifications, as long as this notice is preserved.
9
10 This file is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
12 implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
13 PURPOSE.
14
15
16 Introduction
17 --------------
18
19 GnuPG Made Easy (GPGME) is a C language library that allows to add
20 support for cryptography to a program.  It is designed to make access
21 to public key crypto engines like GnuPG or GpgSM easier for
22 applications.  GPGME provides a high-level crypto API for encryption,
23 decryption, signing, signature verification and key management.
24
25 GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and the
26 Cryptographic Message Syntax (CMS).
27
28 GPGME runs best on GNU/Linux or *BSD systems.  Other Unices may
29 require small portability fixes, please send us your patches.
30
31 See the files COPYING, COPYING.LESSER, and each file for copyright and
32 warranty information.  The file AUTHORS has a list of authors and
33 useful web and mail addresses.
34
35
36 Installation
37 --------------
38
39 See the file INSTALL for generic installation instructions.
40
41 Check that you have unmodified sources.  See below on how to do this.
42 Don't skip it - this is an important step!
43
44 To build GPGME, you need to install libgpg-error (>= 1.8) and
45 Libassuan (>= 2.0.2).
46
47 For support of the OpenPGP protocol (default), you should use the
48 latest version of GnuPG (>= 1.4) , available at:
49 ftp://ftp.gnupg.org/gcrypt/gnupg/
50 For support of the CMS (Cryptographic Message Syntax) protocol, you
51 need a GnuPG version >= 2.0.
52
53 If configure can't find the `gpg' binary in your path, you can specify
54 the location with the --with-gpg=/path/to/gpg argument to configure.
55
56 If configure can't find the `gpgsm' binary in your path, you can
57 specify the location with the --with-gpgsm=/path/to/gpgsm argument to
58 configure.
59
60 On some platforms GPGME based applications might hang at certain
61 operations when using GPGME_PROTOCOL_CMS.  A workaround for this
62 problem is to build with the configure option --disable-fd-passing.
63
64 For building the GIT version of GPGME please see the file README.GIT
65 for more information.
66
67
68 How to Verify the Source
69 --------------------------
70
71 In order to check that the version of GPGME which you are going to
72 install is an original and unmodified one, you can do it in one of the
73 following ways:
74
75 a) If you have a trusted Version of GnuPG installed, you can simply check
76    the supplied signature:
77
78         $ gpg --verify gpgme-x.y.z.tar.gz.sig
79
80    This checks that the detached signature gpgme-x.y.z.tar.gz.sig is
81    indeed a a signature of gpgme-x.y.z.tar.gz.  The key used to create
82    this signature is either of:
83
84    "pub  2048R/4F25E3B6 2011-01-12 Werner Koch (dist sig)"
85    "pub  1024D/87978569 1999-05-13
86                         Marcus Brinkmann <Marcus.Brinkmann@ruhr-uni-bochum.de>
87                         Marcus Brinkmann <mb@g10code.com>"
88
89    If you do not have this key, you can get it from any keyserver.  You
90    have to make sure that this is really the key and not a faked one.
91    You can do this by comparing the output of:
92
93         $ gpg --fingerprint 0x4F25E3B6
94
95    with the fingerprint published elsewhere.
96
97 b) If you don't have any of the above programs, you have to verify
98    the SHA1 checksum:
99
100         $ sha1sum gpgme-x.y.z.tar.gz
101
102    This should yield an output _similar_ to this:
103
104    fd9351b26b3189c1d577f0970f9dcadc3412def1  gpgme-x.y.z.tar.gz
105
106    Now check that this checksum is _exactly_ the same as the one
107    published via the announcement list and probably via Usenet.
108
109
110 Documentation
111 ---------------
112
113 For information how to use the library you can read the info manual,
114 which is also a reference book, in the doc/ directory.  The programs
115 in the tests/gpg/ directory may also prove useful.
116
117 Please subscribe to the gnupg-devel@gnupg.org mailing list if you want
118 to do serious work.
119
120 For hacking on GPGME, please have a look at doc/HACKING.