diff --git a/doc/ChangeLog b/doc/ChangeLog new file mode 100644 index 00000000..7527b2bc --- /dev/null +++ b/doc/ChangeLog @@ -0,0 +1,8 @@ +2002-01-16 Marcus Brinkmann + + * ChangeLog: New file. + * gpgme.texi: Likewise. + * gpl.texi: Likewise. + * fdl.texi: Likewise. + * Makefile.am (info_TEXINFOS): New variable. + (gpgme_TEXINFOS): Likewise. diff --git a/doc/Makefile.am b/doc/Makefile.am index 97697608..ce118100 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -21,7 +21,5 @@ EXTRA_DIST = gdoc - - - - +info_TEXINFOS = gpgme.texi +gpgme_TEXINFOS = gpl.texi fdl.texi diff --git a/doc/fdl.texi b/doc/fdl.texi new file mode 100644 index 00000000..50028ab5 --- /dev/null +++ b/doc/fdl.texi @@ -0,0 +1,402 @@ +@node Free Documentation License +@appendix GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@center Version 1.1, March 2000 + +@display +Copyright @copyright{} 2000 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document @dfn{free} in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The ``Document'', below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as ``you''. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input format, +@acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed +for human modification. Opaque formats include PostScript, +@acronym{PDF}, proprietary formats that can be read and edited only by +proprietary word processors, @acronym{SGML} or @acronym{XML} for which +the @acronym{DTD} and/or processing tools are not generally available, +and the machine-generated @acronym{HTML} produced by some word +processors for output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has less than five). + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section entitled ``History'', and its title, and add to +it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +In any section entitled ``Acknowledgments'' or ``Dedications'', +preserve the section's title, and preserve in the section all the +substance and tone of each of the contributor acknowledgments +and/or dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section as ``Endorsements'' +or to conflict in title with any Invariant Section. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled ``History'' +in the various original documents, forming one section entitled +``History''; likewise combine any sections entitled ``Acknowledgments'', +and any sections entitled ``Dedications''. You must delete all sections +entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an ``aggregate'', and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +@end enumerate + +@page +@appendixsubsec ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being @var{list their titles}, with the + Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. + A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have no Invariant Sections, write ``with no Invariant Sections'' +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write ``no Front-Cover Texts'' instead of +``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/doc/gpgme.texi b/doc/gpgme.texi new file mode 100644 index 00000000..bc308b05 --- /dev/null +++ b/doc/gpgme.texi @@ -0,0 +1,1846 @@ +\input texinfo @c -*- Texinfo -*- +@setfilename gpgme.info +@settitle The `GnuPG Made Easy' Reference Manual + +@c TODO: +@c GpgmeError gpgme_op_import ( GpgmeCtx c, GpgmeData keydata ); +@c GpgmeError gpgme_op_export ( GpgmeCtx c, GpgmeRecipients recp, +@c GpgmeData keydata ); +@c GpgmeError gpgme_op_genkey ( GpgmeCtx c, const char *parms, +@c GpgmeData pubkey, GpgmeData seckey ); +@c GpgmeError gpgme_op_delete ( GpgmeCtx c, const GpgmeKey key, int allow_secret); +@c char *gpgme_get_op_info (GpgmeCtx c, int reserved); +@c void gpgme_cancel (GpgmeCtx c); +@c GpgmeCtx gpgme_wait (GpgmeCtx c, int hang); +@c char *gpgme_get_notation (GpgmeCtx c); +@c void gpgme_register_idle (void (*fnc)(void)); + +@dircategory GNU Libraries +@direntry +* @acronym{GPGME}: (gpgme) Adding support for cryptography to your program. +@end direntry + +@include version.texi + +@c Unify some of the indices. +@syncodeindex tp fn +@syncodeindex pg fn + +@ifinfo +This file documents the @acronym{GPGME} library. + +This is Edition @value{EDITION}, last updated @value{UPDATED}, of +@cite{The `GnuPG Made Easy' Reference Manual}, for Version +@value{VERSION}. + +Copyright @copyright{} 2002 g10 Code GmbH. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``Free Software Needs Free Documentation'' and +``GNU Lesser General Public License'', the Front-Cover texts being (a) +(see below), and with the Back-Cover Texts being (b) (see below). A +copy of the license is included in the section entitled ``GNU Free +Documentation License''. + +@end ifinfo + +@iftex +@shorttitlepage The `GnuPG Made Easy' Reference Manual +@end iftex +@titlepage +@center @titlefont{The `GnuPG Made Easy'} +@sp 1 +@center @titlefont{Reference Manual} +@sp 6 +@center Edition @value{EDITION} +@sp 1 +@center last updated @value{UPDATED} +@sp 1 +@center for version @value{VERSION} +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 2001 g10Code GmbH. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``Free Software Needs Free Documentation'' and +``GNU Lesser General Public License'', the Front-Cover texts being (a) +(see below), and with the Back-Cover Texts being (b) (see below). A +copy of the license is included in the section entitled ``GNU Free +Documentation License''. +@end titlepage +@page + +@ifnottex +@node Top +@top Main Menu +This is Edition @value{EDITION}, last updated @value{UPDATED}, of +@cite{The `GnuPG Made Easy' Reference Manual}, for Version +@value{VERSION} of the GNU Mach microkernel. +@end ifnottex + +@menu +* Introduction:: How to use this manual. +* Preperation:: What you should do before using the library. +* Protocols and Engines:: Supported crypto protocols. +* Error Handling:: Error numbers and their meanings. +* Exchanging Data:: Passing data to and from @acronym{GPGME}. +* Contexts:: Handling @acronym{GPGME} contexts. + +Appendices + +* Copying:: The GNU General Public License says how you + can copy and share `GnuPG Made Easy'. +* Free Documentation License:: This manual is under the GNU Free + Documentation License. + +Indices + +* Concept Index:: Index of concepts and programs. +* Function and Data Index:: Index of functions, variables and data types. + + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Getting Started:: Purpose of the manual, and how to use it. +* Features:: Reasons to install and use @acronym{GPGME}. +* Overview:: Basic architecture of the @acronym{GPGME} library. + +Preperation + +* Header:: What header file you need to include. +* Building the source:: Compiler options to be used. +* Library version check:: Getting and verifying the library version. + +Protocols and Engines + +* Engine version check:: Verifying the engine version. +* Engine information:: Obtaining more information about the engines. +* OpenPGP:: Support for the OpenPGP protocol. +* Cryptographic Message Syntax:: Support for the CMS. + +Error Handling + +* Error values:: A list of all error values used. +* Error strings:: How to get a descriptive string from a value. + +Exchanging Data + +* Creating data buffers:: Creating new data buffers. +* Destroying data buffers:: Releasing data buffers. +* Manipulating data buffers:: Operations on data buffers. + +Contexts + +* Creating contexts:: Creating new @acronym{GPGME} contexts. +* Destroying contexts:: Releasing @acronym{GPGME} contexts. +* Context attributes:: Setting properties of a context. +* Key Management:: Managing keys with @acronym{GPGME}. +* Trust Item Management:: Managing trust items with @acronym{GPGME}. +* Crypto Operations:: Using a context for cryptography. + +Context attributes + +* Protocol selection:: Selecting the protocol used by a context. +* @acronym{ASCII} armor:: Requesting @acronym{ASCII} armored output. +* Text mode:: Choosing canonical text mode. +* Key listing mode:: Selecting key listing mode. +* Passphrase callback:: Getting the passphrase from the user. +* Progress meter callback:: Being informed about the progress. + +Key Management + +* Listing keys:: Browsing the list of available keys. +* Information about keys:: Requesting detailed information about keys. +* Manipulating keys:: Operations on keys. + +Trust Item Management + +* Listing trust items:: Browsing the list of available trust items. +* Information about trust items:: Requesting detailed information about trust items. +* Manipulating trust items:: Operations on trust items. + +Crypto Operations + +* Decrypt:: Decrypting a ciphertext. +* Verify:: Verifying a signature. +* Decrypt and verify:: Decrypting a signed ciphertext. +* Sign:: Creating a signature. +* Encrypt:: Encrypting a plaintext. + +Sign + +* Selecting signers:: How to choose the keys to sign with. +* Creating a signature:: How to create a signature. + + +@end detailmenu +@end menu + +@node Introduction +@chapter Introduction + +`GnuPG Made Easy' (@acronym{GPGME}) is a C language library that +allows to add support for cryptography to a program. It is designed +to make access to crypto engines like GnuPG or GpgSM easier for +applications. @acronym{GPGME} provides a high-level crypto API for +encryption, decryption, signing, signature verification and key +management. + +@acronym{GPGME} uses GnuPG and GpgSM as its backends to support +OpenPGP and the Cryptograhic Message Syntax (CMS). + +@menu +* Getting Started:: Purpose of the manual, and how to use it. +* Features:: Reasons to install and use @acronym{GPGME}. +* Overview:: Basic architecture of the @acronym{GPGME} library. +@end menu + + +@node Getting Started +@section Getting Started + +This library documents the @acronym{GPGME} library programming +interface. All functions and data types provided by the library are +explained. + +The reader is assumed to posess basic knowledge about cryptography in +general, and public key cryptography in particular. The underlying +cryptographic engines that are used by the library are not explained, +but where necessary, special features or requirements by an engine are +mentioned as far as they are relevant to @acronym{GPGME} or its users. + +This manual can be used in several ways. If read from the beginning +to the end, it gives a good introduction into the library and how it +can be used in an application. Forward references are included where +necessary. Later on, the manual can be used as a reference manual to +get just the information needed about any particular interface of the +library. Experienced programmers might want to start looking at the +examples at the end of the manual, and then only read up those parts +of the interface which are unclear. + + +@node Features +@section Features + +@acronym{GPGME} has a couple of advantages over other libraries doing +a similar job, and over implementing support for GnuPG or other crypto +engines into your application directly. + +@table @asis +@item it's free software +Anybody can use, modify, and redistribute it under the terms of the GNU +General Public License (@pxref{Copying}). + +@item it's flexible +@acronym{GPGME} provides transparent support for several cryptographic +protocols by different engines. Currently, @acronym{GPGME} supports +the OpenPGP protocol using GnuPG as the backend, and the Cryptographic +Message Syntax using GpgSM as the backend. + +@item it's easy +@acronym{GPGME} hides the differences between the protocols and +engines from the programmer behind an easy-to-use interface. This way +the programmer can focus on the other parts of the program, and still +integrate strong cryptography in his application. Once support for +@acronym{GPGME} has been added to a program, it is easy to add support +for other crypto protocols once @acronym{GPGME} backends provide them. +@end table + + +@node Overview +@section Overview + +@acronym{GPGME} provides a data abstraction that is used to pass data +to the crypto engine, and receive returned data from it. Data can be +read from memory or from files, but it can also be provided by a +callback function. + +The actual cryptographic operations are always set within a context. +A context provides configuration parameters that define the behaviour +of all operations performed within it. Only one operation per context +is allowed at any time, but when one operation is finished, you can +run the next operation in the same context. There can be more than +one context, and all can run different operations at the same time. + +Furthermore, @acronym{GPGME} has rich key management facilities +including listing keys, querying their attributes, generating, +importing, exporting and deleting keys, and acquiring information +about the trust path. + +@strong{Caution:} The @acronym{GPGME} library is not thread-safe. It +will be to some extent in the future, but currently great care has to +be taken if @acronym{GPGME} is used in a multi-threaded environment. + + +@node Preperation +@chapter Preperation + +To use @acronym{GPGME}, you have to perform some changes to your +sources and the build system. The necessary changes are small and +explained in the following sections. At the end of this chapter, it +is described how the library is initialized, and how the requirements +of the library are verified. + +@menu +* Header:: What header file you need to include. +* Building the source:: Compiler options to be used. +* Library version check:: Getting and verifying the library version. +@end menu + + +@node Header +@section Header + +All interfaces (data types and functions) of the library are defined +in the header file `gpgme.h'. You must include this in all programs +using the library, either directly or through some other header file, +like this: + +@example +#include +@end example + +The name space of @acronym{GPGME} is @code{gpgme_*} for function +names, @code{Gpgme*} for data types and @code{GPGME_*} for other +symbols. + + +@node Building the source +@section Building the source + +If you want to compile a source file including the `gpgme.h' header +file, you must make sure that the compiler can find it in the +directory hierarchy. This is accomplished by adding the path to the +directory in which the header file is located to the compilers include +file search path (via the @option{-I} option). + +However, the path to the include file is determined at the time the +source is configured. To solve this problem, gpgme ships with a small +helper program @command{gpgme-config} that knows about the path to the +include file and other configuration options. The options that need +to be added to the compiler invocation at compile time are output by +the @option{--cflags} option to @command{gpgme-config}. The following +example shows how it can be used at the command line: + +@example +gcc -c foo.c `gpgme-config --cflags` +@end example + +Adding the output of @samp{gpgme-config --cflags} to the compilers +command line will ensure that the compiler can find the @acronym{GPGME} header +file. + +A similar problem occurs when linking the program with the library. +Again, the compiler has to find the library files. For this to work, +the path to the library files has to be added to the library search +path (via the @option{-L} option). For this, the option +@option{--libs} to @command{gpgme-config} can be used. For +convenience, this option also outputs all other options that are +required to link the program with @acronym{GPGME} (in particular, the +@samp{-lgpgme} option). The example shows how to link @file{foo.o} +with the @acronym{GPGME} library to a program @command{foo}. + +@example +gcc -o foo foo.o `gpgme-config --libs` +@end example + +Of course you can also combine both examples to a single command by +specifying both options to @command{gpgme-config}: + +@example +gcc -o foo foo.c `gpgme-config --cflags --libs` +@end example + + +@node Library version check +@section Library version check + +@deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}}) +The function @code{gpgme_check_version} has three purposes. It can be +used to retrieve the version number of the library. In addition it +can verify that the version number is higher than a certain required +version number. In either case, the function initializes some +sub-systems, and for this reason alone it must be invoked early in +your program, before you make use of the other functions in +@acronym{GPGME}. + +If @var{required_version} is @code{NULL}, the function returns a +pointer to a statically allocated string containing the version number +of the library. + +If @var{required_version} is not @code{NULL}, it should point to a +string containing a version number, and the function checks that the +version of the library is at least as high as the version number +provided. In this case, the function returns a pointer to a +statically allocated string containing the version number of the +library. If @var{REQUIRED_VERSION} is not a valid version number, or +if the version requirement is not met, the function returns +@code{NULL}. + +If you use a version of a library that is backwards compatible with +older releases, but contains additional interfaces which your program +uses, this function provides a run-time check if the necessary +features are provided by the installed version of the library. +@end deftypefun + + +@node Protocols and Engines +@chapter Protocols and Engines + +@acronym{GPGME} supports several cryptographic protocols, however, it +does not implement them. Rather it uses backends (also called +engines) which implement the protocol. @acronym{GPGME} uses +inter-process communication to pass data back and forth between the +application and the backend, but the details of the communication +protocol and invocation of the backends is completely hidden by the +interface. All complexity is handled by @acronym{GPGME}. Where an +exchange of information between the application and the backend is +necessary, @acronym{GPGME} provides the necessary callback function +hooks and further interfaces. + +@deftp {Data type} {enum GpgmeProtocol} +The @code{GpgmeProtocol} type specifies the set of possible protocol +values that are supported by @acronym{GPGME}. The following protocols +are supported: + +@table @code +@item GPGME_PROTOCOL_OpenPGP +This specifies the OpenPGP protocol. +@item GPGME_PROTOCOL_CMS +This specifies the Cryptographic Message Syntax. +@end table +@end deftp + +@menu +* Engine version check:: Verifying the engine version. +* Engine information:: Obtaining more information about the engines. +* OpenPGP:: Support for the OpenPGP protocol. +* Cryptographic Message Syntax:: Support for the CMS. +@end menu + + +@node Engine version check +@section Engine version check + +@deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}}) +The function @code{gpgme_engine_check_version} verifies that the +engine implementing the protocol @var{PROTOCOL} is installed in the +expected path and meets the version requirement of @acronym{GPGME}. + +This function returns @code{GPGME_No_Error} if the engine is available +and @code{GPGME_Invalid_Engine} if it is not. +@end deftypefun + +@deftypefun GpgmeError gpgme_check_engine (void) +The function @code{gpgme_check_engine} is equivalent to + +@example +gpgme_engine_check_version (GPGME_PROTOCOL_OpenPGP); +@end example + +This function is deprecated and provided for backwards compatibility +only. It is obsoleted by @code{gpgme_engine_check_version}. +@end deftypefun + + +@node Engine information +@section Engine information + +@deftypefun {const char *} gpgme_get_engine_info (void) +The function @code{gpgme_get_engine_info} returns an @acronym{XML} +string containing information about the available protocols and the +engine which implement them. The following information is returned +for each engine: + +@table @samp +@item +The name of the protocol. +@item +The version of the engine. +@item +The path to the engine binary. +@end table + +A string is always returned. If an error occurs, the string will +contain an @samp{} tag with a description of the failure. +@end deftypefun + +Here is the example output of what @code{gpgme_get_engine_info} might +return on your system: + +@example + + + OpenPGP + 1.0.6 + /usr/bin/gpg + + + CMS + 0.0.0 + /usr/bin/gpgsm + + +@end example + + +@node OpenPGP +@section OpenPGP + +OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard. +This is the first protocol that was supported by @acronym{GPGME}. + +The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}. + + +@node Cryptographic Message Syntax +@section Cryptographic Message Syntax + +@acronym{CMS} is implemented by GpgSM, the S/MIME implementation for +GnuPG. + +The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}. + + +@node Error Handling +@chapter Error Handling + +Many functions in @acronym{GPGME} can return an error if they fail. +For this reason, the application should always catch the error +condition and take appropriate measures, for example by releasing the +resources and passing the error up to the caller, or by displaying a +descriptive message to the user and cancelling the operation. + +Some error values do not indicate a system error or an error in the +operation, but the result of an operation that failed properly. For +example, if you try to decrypt a tempered message, the decryption will +fail. Another error value actually means that the end of a data +buffer or list has been reached. The following descriptions explain +what each error message means in general. Some error values have +specific meanings if returned by a specific function. Such cases are +described in the documentation of those functions. + +@menu +* Error values:: A list of all error values used. +* Error strings:: How to get a descriptive string from a value. +@end menu + + +@node Error values +@section Error values + +@deftp {Data type} {enum GpgmeError} +The @code{GpgmeError} type specifies the set of all error values that +are used by @acronym{GPGME}. Possible values are: + +@table @code +@item GPGME_EOF +This value indicates the end of a list, buffer or file. + +@item GPGME_No_Error +This value indicates success. The value of this error is @code{0}. + +@item GPGME_General_Error +This value means that something went wrong, but either there is not +enough information about the problem to return a more useful error +value, or there is no seperate error value for this type of problem. + +@item GPGME_Out_Of_Core +This value means that an out-of-memory condition occured. + +@item GPGME_Invalid_Value +This value means that some user provided data was out of range. This +can also refer to objects. For example, if an empty @code{GpgmeData} +object was expected, but one containing data was provided, this error +value is returned. + +@item GPGME_Busy +This value is returned if you try to start a new operation in a +context that is already busy with some earlier operation which was not +canceled or finished yet. + +@item GPGME_No_Request +This value is in some sense the opposite of @code{GPGME_Busy}. There +is no pending operation, but it is required for the function to +succeed. + +@item GPGME_Exec_Error +This value means that an error occured when trying to spawn a child +process. + +@item GPGME_Too_Many_Procs +This value means that there are too many active backend processes. + +@item GPGME_Pipe_Error +This value means that the creation of a pipe failed. + +@item GPGME_No_Recipients +This value means that no recipients for a message have been set. + +@item GPGME_No_Data +This value means that a @code{GpgmeData} object which was expected to +have content was found empty. + +@item GPGME_Conflict +This value means that a conflict of some sort occured. + +@item GPGME_Not_Implemented +This value indicates that the specific function (or operation) is not +implemented. This error should never happen. It can only occur if +you use certain values or configuration options which do not work, +but for which we think that they should work at some later time. + +@item GPGME_Read_Error +This value means that an I/O read operation failed. + +@item GPGME_Write_Error +This value means that an I/O write operation failed. + +@item GPGME_Invalid_Type +This value means that a user provided object was of a wrong or +incompatible type. Usually this refers to the type of a +@code{GpgmeData} object. + +@item GPGME_Invalid_Mode +This value means that a @code{GpgmeData} object has an incorrect mode +of operation (for example, doesn't support output although it is +attempted to use it as an output buffer). + +@item GPGME_File_Error +This value means that a file I/O operation failed. The value of +@code{errno} contains the system error value. + +@item GPGME_Decryption_Failed +This value indicates that a decryption operation was unsuccessful. + +@item GPGME_No_Passphrase +This value means that the user did not provide a passphrase when +requested. + +@item GPGME_Canceled +This value means that the operation was canceled. + +@item GPGME_Invalid_Key +This value means that a key was invalid. + +@item GPGME_Invalid_Engine +This value means that the engine that implements the desired protocol +is currently not available. This can either be because the sources +were configured to exclude support for this engine, or because the +engine is not installed properly. +@end table +@end deftp + + +@node Error strings +@section Error strings + +@deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}}) +The function @code{gpgme_strerror} returns a pointer to a statically +allocated string containing a description of the error with the error +value @var{err}. This string can be used to output a diagnostic +message to the user. +@end deftypefun + + +@node Exchanging Data +@chapter Exchanging Data + +A lot of data has to be exchanged between the user and the crypto +engine, like plaintext messages, ciphertext, signatures and +information about the keys. The technical details about exchanging +the data information are completely abstracted by @acronym{GPGME}. +The user provides and receives the data via @code{GpgmeData} objects, +regardless of the communication protocol between @acronym{GPGME} and +the crypto engine in use. + +@deftp {Data type} {GpgmeData} +The @code{GpgmeData} type is a handle for a container for generic +data, which is used by @acronym{GPGME} to exchange data with the user. +@end deftp + +@menu +* Creating data buffers:: Creating new data buffers. +* Destroying data buffers:: Releasing data buffers. +* Manipulating data buffers:: Operations on data buffers. +@end menu + + +@node Creating data buffers +@section Creating data buffers + +@deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}}) +The function @code{gpgme_data_new} creates a new @code{GpgmeData} +object and returns a handle for it in @var{dh}. The data object is +initially empty. + +The function returns @code{GPGME_No_Error} if the data object was +successfully created, @code{GPGME_Invalid_Value} if @var{dh} is not a +valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is +available. +@end deftypefun + +@deftypefun GpgmeError gpgme_data_new_from_mem (@w{GpgmeData *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}}) +The function @code{gpgme_data_new_from_mem} creates a new +@code{GpgmeData} object and fills it with @var{size} bytes starting +from @var{buffer}. + +If @var{copy} is not zero, a private copy of the data is made. If +@var{copy} is zero, the data is taken from the specified buffer as +needed, and the user has to ensure that the buffer remains valid for +the whole life span of the data object. + +The function returns @code{GPGME_No_Error} if the data object was +successfully created, @code{GPGME_Invalid_Value} if @var{dh} or +@var{buffer} is not a valid pointer, and @code{GPGME_Out_Of_Core} if +not enough memory is available. +@end deftypefun + +@deftypefun GpgmeError gpgme_data_new_from_file (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}}) +The function @code{gpgme_data_new_from_file} creates a new +@code{GpgmeData} object and fills it with the content of the file +@var{filename}. + +If @var{copy} is not zero, the whole file is read in at initialization +time and the file is not used anymore after that. This is the only +mode supported currently. Later, a value of zero for @var{copy} might +cause all reads to be delayed until the data is needed, but this is +not yet implemented. + +The function returns @code{GPGME_No_Error} if the data object was +successfully created, @code{GPGME_Invalid_Value} if @var{dh} or +@var{filename} is not a valid pointer, @code{GPGME_File_Error} if an +I/O operation fails, @code{GPGME_Not_Implemented} if @var{code} is +zero, and @code{GPGME_Out_Of_Core} if not enough memory is available. +@end deftypefun + +@deftypefun GpgmeError gpgme_data_new_from_filepart (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{off_t @var{length}}) +The function @code{gpgme_data_new_from_filepart} creates a new +@code{GpgmeData} object and fills it with a part of the file specified +by @var{filename} or @var{fp}. + +Exactly one of @var{filename} and @var{fp} must be non-zero, the other +must be zero. The argument that is not zero specifies the file from +which @var{length} bytes are read into the data object, starting from +@var{offset}. + +The function returns @code{GPGME_No_Error} if the data object was +successfully created, @code{GPGME_Invalid_Value} if @var{dh} and +exactly one of @var{filename} and @var{fp} is not a valid pointer, +@code{GPGME_File_Error} if an I/O operation fails, and +@code{GPGME_Out_Of_Core} if not enough memory is available. +@end deftypefun + + +@deftypefun GpgmeError gpgme_data_new_with_read_cb (@w{GpgmeData *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}}) +The function @code{gpgme_data_new_with_read_cb} creates a new +@code{GpgmeData} object and uses the callback function @var{readfunc} +to retrieve the data on demand. As the callback function can supply +the data in any way it wants, this is the most flexible data type +@acronym{GPGME} provides. However, it can not be used to write data. + +The callback function receives @var{hook_value} as its first argument +whenever it is invoked. It should return up to @var{count} bytes in +@var{buffer}, and return the number of bytes actually read in +@var{nread}. It may return @code{0} in @var{nread} if no data is +currently available. To indicate @code{EOF} the function should +return with an error code of @code{-1} and set @var{nread} to +@code{0}. The callback function may support to reset its internal +read pointer if it is invoked with @var{buffer} and @var{nread} being +@code{NULL} and @var{count} being @code{0}. + +The function returns @code{GPGME_No_Error} if the data object was +successfully created, @code{GPGME_Invalid_Value} if @var{dh} or +@var{readfunc} is not a valid pointer, and @code{GPGME_Out_Of_Core} if +not enough memory is available. +@end deftypefun + + +@node Destroying data buffers +@section Destroying data buffers + +@deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}}) +The function @code{gpgme_data_release} destroys the data object with +the handle @var{dh}. It releases all associated resources that were +not provided by the user in the first place. +@end deftypefun + +@deftypefun {char *} gpgme_data_release_and_get_mem (@w{GpgmeData @var{dh}}, @w{size_t *@var{length}}) +The function @code{gpgme_data_release_and_get_mem} is like +@code{gpgme_data_release}, except that it returns the data buffer and +its length that was provided by the object. + +The user has to release the buffer with @code{free}. In case the user +provided the data buffer in non-copy mode, a copy will be made for +this purpose. + +In case an error returns, or there is no suitable data buffer that can +be returned to the user, the function will return @code{NULL}. +@end deftypefun + + +@node Manipulating data buffers +@section Manipulating data buffers + +@deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}}) +The function @code{gpgme_data_read} reads up to @var{length} bytes +from the data object with the handle @var{dh} into the space starting +at @var{buffer}. The actual amount read is returned in @var{nread}. + +If @var{buffer} is @code{NULL}, the function returns the amount of +bytes available in @var{nread} without changing the read pointer. +This is not supported by all types of data objects. If this function +is not supported, @code{GPGME_Invalid_Type} is returned. + +If the end of the data object is reached, the function returns +@code{GPGME_EOF} and sets @var{nread} to zero. + +In all other cases, the function returns @code{GPGME_No_Error} if the +operation was successfully performed and @code{GPGME_Invalid_Value} if +@var{dh} is not a valid pointer. +@end deftypefun + +@deftypefun GpgmeError gpgme_data_rewind (@w{GpgmeData @var{dh}}) +The function @code{gpgme_data_rewind} resets the read pointer of the +data object with the handle @var{dh}, so that a subsequent +@code{gpgme_data_read} operation starts at the beginning of the data. + +The function returns @code{GPGME_No_Error} if the operation was +successfully performed, @code{GPGME_Not_Implemented} if the operation +is not supported (for example, by a read callback function supplied by +the user) and @code{GPGME_Invalid_Value} if @var{dh} is not a valid +pointer. +@end deftypefun + +@deftypefun GpgmeError gpgme_data_write (@w{GpgmeData @var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{length}}) +The function @code{gpgme_data_write} writes @var{length} bytes +starting from @var{buffer} into the data object with the handle +@var{dh} at the current write position. + +The function returns @code{GPGME_No_Error} if the operation was +successfully performed, @code{GPGME_Invalid_Value} if @var{dh} or +@var{buffer} is not a valid pointer, @code{GPGME_Invalid_Type} or +@code{GPGME_Invalid_Mode} if the data object type does not support +writing, and @code{GPGME_Out_Of_Core} if not enough memory is +available. +@end deftypefun + +@deftp {Data type} {enum GpgmeDataType} +The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object. +The following data types are available: + +@table @code +@item GPGME_DATA_TYPE_NONE +This specifies that the type is not yet determined. + +@item GPGME_DATA_TYPE_MEM +This specifies that the data is stored in memory. + +@item GPGME_DATA_TYPE_FD +This type is not implemented. + +@item GPGME_DATA_TYPE_FILE +This type is not implemented. + +@item GPGME_DATA_TYPE_CB +This type specifies that the data is provided by a callback function +implemented by the user. +@end table +@end deftp + +@deftypefun GpgmeDataType gpgme_data_get_type (@w{GpgmeData @var{dh}}) +The function @code{gpgme_data_get_type} returns the type of the data +object with the handle @var{dh}. If @var{dh} is not a valid pointer, +@code{GPGME_DATA_TYPE_NONE} is returned. +@end deftypefun + + +@node Contexts +@chapter Contexts + +All cryptograhic operations in @acronym{GPGME} are performed within a +context, which contains the internal state of the operation as well as +configuration parameters. By using several contexts you can run +several cryptographic operations in parallel, with different +configuration. + +@deftp {Data type} {GpgmeCtx} +The @code{GpgmeCtx} type is a handle for a @acronym{GPGME} context, +which is used to hold the configuration, status and result of +cryptographic operations. +@end deftp + +@menu +* Creating contexts:: Creating new @acronym{GPGME} contexts. +* Destroying contexts:: Releasing @acronym{GPGME} contexts. +* Context attributes:: Setting properties of a context. +* Key Management:: Managing keys with @acronym{GPGME}. +* Trust Item Management:: Managing trust items with @acronym{GPGME}. +* Crypto Operations:: Using a context for cryptography. +@end menu + + +@node Creating contexts +@section Creating contexts + +@deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}}) +The function @code{gpgme_data_new} creates a new @code{GpgmeCtx} +object and returns a handle for it in @var{ctx}. + +The function returns @code{GPGME_No_Error} if the context was +successfully created, @code{GPGME_Invalid_Value} if @var{ctx} is not a +valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is +available. +@end deftypefun + + + +@node Destroying contexts +@section Destroying contexts + +@deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_release} destroys the context with the handle +@var{ctx} and releases all associated resources. +@end deftypefun + + +@node Context attributes +@section Context attributes + +@menu +* Protocol selection:: Selecting the protocol used by a context. +* @acronym{ASCII} armor:: Requesting @acronym{ASCII} armored output. +* Text mode:: Choosing canonical text mode. +* Key listing mode:: Selecting key listing mode. +* Passphrase callback:: Getting the passphrase from the user. +* Progress meter callback:: Being informed about the progress. +@end menu + + +@node Protocol selection +@subsection Protocol selection + +@deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}}) +The function @code{gpgme_set_protocol} sets the protocol used within +the context @var{ctx} to @var{proto}. All crypto operations will be +performed by the crypto engine configured for that protocol. +@xref{Protocols and Engines}. + +Setting the protocol with @code{gpgme_set_protocol} does not check if +the crypto engine for that protocol is available and installed +correctly. @xref{Engine version check}. + +The function returns @code{GPGME_No_Error} if the protocol could be +set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is +not a valid protocol. +@end deftypefun + + +@node @acronym{ASCII} armor +@subsection @acronym{ASCII} armor + +@deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}}) +The function @code{gpgme_set_armor} specifies if the output should be +@acronym{ASCII} armoured. By default, output is not @acronym{ASCII} +armoured. + +@acronym{ASCII} armoured output is disabled if @var{yes} is zero, and +enabled otherwise. +@end deftypefun + +@deftypefun int gpgme_get_armor (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_get_armor} returns 1 if the output is +@acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is +not a valid pointer. +@end deftypefun + + +@node Text mode +@subsection Text mode + +@deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}}) +The function @code{gpgme_set_textmode} specifies if canonical text mode +should be used. By default, text mode is not used. + +Text mode is for example used for the RFC2015 signatures; note that +the updated RFC 3156 mandates that the mail user agent does some +preparations so that text mode is not needed anymore. + +Canonical text mode is disabled if @var{yes} is zero, and enabled +otherwise. +@end deftypefun + +@deftypefun int gpgme_get_textmode (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_get_textmode} returns 1 if canonical text +mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a +valid pointer. +@end deftypefun + + +@node Key listing mode +@subsection Key listing mode + +@deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}}) +The function @code{gpgme_set_keylist_mode} changes the default +behaviour of the key listing functions. Defined values for @var{mode} +are: + +@table @code +@item 0 +Normal listing. +@item 1 +Fast listing without information about the key validity. +@end table +@end deftypefun + + +@node Passphrase callback +@subsection Passphrase callback + +@deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void *@var{r_hd})} +The @code{GpgmePasshraseCb} type is the type of functions usable as +passphrase callback function. + +The string @var{desc} contains a test usable to be displayed to the +user of the application. The function should return a passphrase for +the context when invoked with @var{desc} not being @code{NULL}. + +The user may store information about the resources associated with the +returned passphrase in @var{*r_hd}. When the passphrase is no longer +needed by @acronym{GPGME}, the passphrase callback function will be +called with @var{desc} being @var{NULL}, and @var{r_hd} being the same +as at the first invocation. +@end deftp + +@deftypefun void gpgme_set_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb @var{passfunc}}, @w{void *@var{hook_value}}) +The function @code{gpgme_set_passphrase_cb} sets the function that is +used when a passphrase needs to be provided by the user to +@var{passfunc}. The function @var{passfunc} needs to implemented by +the user, and whenever it is called, it is called with its first +argument being @var{hook_value}. By default, no passphrase callback +function is set. + +Not all crypto engines require this callback to retrieve the +passphrase. It is better if the engine retrieves the passphrase from +a trusted agent (a daemon process), rather than having each user to +implement their own passphrase query. + +The user can disable the use of a passphrase callback function by +calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being +@code{NULL}. +@end deftypefun + + +@node Progress meter callback +@subsection Progress meter callback + +@deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})} +The @code{GpgmeProgressCb} type is the type of functions usable as +progress callback function. + +The arguments are specific to the crypto engine. More information +about the progress information returned from the GnuPG engine can be +found in the GnuPG source code in the file @file{doc/DETAILS} in the +section PROGRESS. +@end deftp + +@deftypefun void gpgme_set_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb @var{progfunc}}, @w{void *@var{hook_value}}) +The function @code{gpgme_set_progress_cb} sets the function that is +used when progress information about a cryptographic operation is +available. The function @var{progfunc} needs to implemented by the +user, and whenever it is called, it is called with its first argument +being @var{hook_value}. By default, no progress callback function +is set. + +Setting a callback function allows an interactive program to display +progress information about a long operation to the user. + +The user can disable the use of a progress callback function by +calling @code{gpgme_set_progress_cb} with @var{progfunc} being +@code{NULL}. +@end deftypefun + + +@node Key Management +@section Key Management + +Some of the cryptographic operations require that recipients or +signers are specified. This is always done by specifying the +respective keys that should be used for the operation. The following +section describes how such keys can be selected and manipulated. + +@deftp {Data type} GpgmeKey +The @code{GpgmeKey} type is a handle for a public or secret key, and +is used to select the key for operations involving it. + +A key can contain several user IDs and sub keys. +@end deftp + +@menu +* Listing keys:: Browsing the list of available keys. +* Information about keys:: Requesting detailed information about keys. +* Manipulating keys:: Operations on keys. +@end menu + + +@node Listing keys +@subsection Listing keys + +@deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}}) +The function @code{gpgme_op_keylist_start} initiates a key listing +operation inside the context @var{ctx}. It sets everything up so that +subsequent invocations of @code{gpgme_op_keylist_next} return the keys +in the list. + +If @var{pattern} is @code{NULL}, all available keys are returned. +Otherwise, @var{pattern} contains an engine specific expression that +is used to limit the list to all keys matching the pattern. + +If @var{secret_only} is not @code{0}, the list is restricted to secret +keys only. + +The context will be busy until either all keys are received (and +@code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or +@code{gpgme_op_keylist_end} is called to finish the operation. + +The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a +valid pointer, and passes through any errors that are reported by the +crypto engine support routines. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}}) +The function @code{gpgme_op_keylist_next} returns the next key in the +list created by a previous @code{gpgme_op_keylist_start} operation in +the context @var{ctx}. The key will have one reference for the user. +@xref{Manipulating keys}. + +This is the only way to get at @code{GpgmeKey} objects in +@acronym{GPGME}. + +If the last key in the list has already been returned, +@code{gpgme_op_keylist_next} returns @code{GPGME_EOF}. + +The function returns @code{GPGME_Invalid_Value} if @var{ctx} or +@var{r_key} is not a valid pointer, @code{GPGME_No_Request} if there +is no pending operation, @code{GPGME_Out_Of_Core} if there is not +enough memory for the operation. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_keylist_end (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_op_keylist_next} ends a pending key list +operation in the context @var{ctx}. + +The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a +valid pointer, @code{GPGME_No_Request} if there is no pending +operation, @code{GPGME_Out_Of_Core} if at some time during the +operation there was not enough memory available. +@end deftypefun + + +@node Information about keys +@subsection Information about keys + +@deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}}) +The function @code{gpgme_key_get_as_xml} returns a string in +@acronym{XML} format describing the key @var{key}. The user has to +release the string with @code{free}. + +The function returns @code{NULL} if @var{key} is not a valid pointer, +or there is not enough memory available. +@end deftypefun + +@deftp {Data type} GpgmeAttr +The @code{GpgmeAttr} type is used to specify a key or trust item +attribute. The following attributes are defined: + +@table @code +@item GPGME_ATTR_KEYID +This is the key ID of a sub key. It is representable as a string. + +For trust items, the trust item refers to the key with this ID. + +@item GPGME_ATTR_FPR +This is the fingerprint of a sub key. It is representable as a +string. + +@item GPGME_ATTR_ALGO +This is the crypto algorithm for which the sub key can be used. It +is representable as a string and as a number. The numbers correspond +to the @code{enum gcry_pk_algos} values in the gcrypt library. + +@item GPGME_ATTR_LEN +This is the key length of a sub key. It is representable as a +number. + +@item GPGME_ATTR_CREATED +This is the timestamp at creation time of a sub key. It is +representable as a number. + +@item GPGME_ATTR_EXPIRE +XXX FIXME + +@item GPGME_ATTR_OTRUST +XXX FIXME (also for trust items) + +@item GPGME_ATTR_USERID +This is a user ID. There can be more than one user IDs in a +@var{GpgmeKey} object. The first one (with index 0) is the primary +user ID. The user ID is representable as a number. + +For trust items, this is the user ID associated with this trust item. + +@item GPGME_ATTR_NAME +This is the name belonging to a user ID. It is representable as a string. + +@item GPGME_ATTR_EMAIL +This is the email address belonging to a user ID. It is representable +as a string. + +@item GPGME_ATTR_COMMENT +This is the comment belonging to a user ID. It is representable as a +string. + +@item GPGME_ATTR_VALIDITY +This is the validity belonging to a user ID. It is representable as a +string and as a number. See below for a list of available validities. + +For trust items, this is the validity that is associated with this +trust item. + +@item GPGME_ATTR_UID_REVOKED +This specifies if a user ID is revoked. It is representable as a +number, and is @code{1} if the user ID is revoked, and @code{0} +otherwise. + +@item GPGME_ATTR_UID_INVALID +This specifies if a user ID is invalid. It is representable as a +number, and is @code{1} if the user ID is invalid, and @code{0} +otherwise. + +@item GPGME_ATTR_LEVEL +This is the trust level of a trust item. + +@item GPGME_ATTR_TYPE +This is the type of a trust item. + +@item GPGME_ATTR_IS_SECRET +This specifies if the key is a secret key. It is representable as a +string or a number. If the key is a secret key, the representation is +``1'' or @code{1}, otherwise it is NULL or @code{0}. + +@item GPGME_ATTR_KEY_REVOKED +This specifies if a sub key is revoked. It is representable as a +number, and is @code{1} if the key is revoked, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_INVALID +This specifies if a sub key is invalid. It is representable as a +number, and is @code{1} if the key is invalid, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_EXPIRED +This specifies if a sub key is expired. It is representable as a +number, and is @code{1} if the key is expired, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_DISABLED +This specifies if a sub key is disabled. It is representable as a +number, and is @code{1} if the key is disabled, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_CAPS +This is a description of the capabilities of a sub key. It is +representable as a string. The string contains the letter ``e'' if +the key can be used for encryption, ``s'' if the key can be used for +signatures, and ``c'' if the key can be used for certifications. + +@item GPGME_ATTR_CAN_ENCRYPT +This specifies if a sub key can be used for encryption. It is +representable as a number, and is @code{1} if the sub key can be used +for encryption, and @code{0} otherwise. + +@item GPGME_ATTR_CAN_SIGN +This specifies if a sub key can be used for signatures. It is +representable as a number, and is @code{1} if the sub key can be used +for signatures, and @code{0} otherwise. + +@item GPGME_ATTR_CAN_CERTIFY +This specifies if a sub key can be used for certifications. It is +representable as a number, and is @code{1} if the sub key can be used +for certifications, and @code{0} otherwise. +@end table +@end deftp + +@deftp {Data type} GpgmeValidity +The @code{GpgmeValidity} type is used to specify the validity of a user ID +in a key. The following validities are defined: + +@table @code +@item GPGME_VALIDITY_UNKNOWN +The user ID is of unknown validity. The string representation of this +validity is ``?''. + +@item GPGME_VALIDITY_UNDEFINED +The validity of the user ID is undefined. The string representation of this +validity is ``q''. + +@item GPGME_VALIDITY_NEVER +The user ID is never valid. The string representation of this +validity is ``n''. + +@item GPGME_VALIDITY_MARGINAL +The user ID is marginally valid. The string representation of this +validity is ``m''. + +@item GPGME_VALIDITY_FULL +The user ID is fully valid. The string representation of this +validity is ``f''. + +@item GPGME_VALIDITY_ULTIMATE +The user ID is ultimately valid. The string representation of this +validity is ``u''. +@end table +@end deftp + +@deftypefun {const char *} gpgme_key_get_string_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_get_string_attr} returns the value of the +string-representable attribute @var{what} of key @var{key}. If the +attribute occurs more than once in the key, the index is specified by +@var{idx}. This applies to attributes of sub keys and user IDs. The +argument @var{reserved} is reserved for later use and should be +@code{NULL}. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_get_ulong_attr} returns the value of the +number-representable attribute @var{what} of key @var{key}. If the +attribute occurs more than once in the key, the index is specified by +@var{idx}. This applies to attributes of sub keys and user IDs. The +argument @var{reserved} is reserved for later use and should be +@code{NULL}. + +The function returns @code{0} if the attribute can't be returned as a +number, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + + +@node Manipulating keys +@subsection Manipulating keys + +@deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}}) +The function @code{gpgme_key_ref} acquires an additional reference for +the key @var{key}. +@end deftypefun + +@deftypefun void gpgme_key_unref (@w{GpgmeKey @var{key}}) +@deftypefunx void gpgme_key_release (@w{GpgmeKey @var{key}}) +The function @code{gpgme_key_ref} releases a reference for the key +@var{key}. If this was the last reference, the key will be destroyed +and all resources associated to it will be released. + +The function @code{gpgme_key_release} is an alias for +@code{gpgme_key_unref}. +@end deftypefun + + +@node Trust Item Management +@section Trust Item Management + +@strong{Caution:} The trust items interface is experimental. + +@deftp {Data type} GpgmeTrustItem +The @code{GpgmeTrustItem} type is a handle for a trust item. +@end deftp + +@menu +* Listing trust items:: Browsing the list of available trust items. +* Information about trust items:: Requesting detailed information about trust items. +* Manipulating trust items:: Operations on trust items. +@end menu + + +@node Listing trust items +@subsection Listing trust items + +@deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}}) +The function @code{gpgme_op_trustlist_start} initiates a trust item +listing operation inside the context @var{ctx}. It sets everything up +so that subsequent invocations of @code{gpgme_op_trustlist_next} return +the trsut items in the list. + +The string @var{pattern} contains an engine specific expression that +is used to limit the list to all trust items matching the pattern. It +can not be the empty string. + +The argument @var{max_level} is currently ignored. + +The context will be busy until either all trust items are received +(and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or +@code{gpgme_op_trustlist_end} is called to finish the operation. + +The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a +valid pointer, and passes through any errors that are reported by the +crypto engine support routines. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}}) +The function @code{gpgme_op_trustlist_next} returns the next trust +item in the list created by a previous @code{gpgme_op_trustlist_start} +operation in the context @var{ctx}. The trust item can be destroyed +with @code{gpgme_trust_item_release}. @xref{Manipulating trust items}. + +This is the only way to get at @code{GpgmeTrustItem} objects in +@acronym{GPGME}. + +If the last trust item in the list has already been returned, +@code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}. + +The function returns @code{GPGME_Invalid_Value} if @var{ctx} or +@var{r_item} is not a valid pointer, @code{GPGME_No_Request} if there +is no pending operation, @code{GPGME_Out_Of_Core} if there is not +enough memory for the operation. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_op_trustlist_next} ends a pending key list +operation in the context @var{ctx}. + +The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a +valid pointer, @code{GPGME_No_Request} if there is no pending +operation, @code{GPGME_Out_Of_Core} if at some time during the +operation there was not enough memory available. +@end deftypefun + + +@node Information about trust items +@subsection Information about trust items + +Trust items have attributes which can be queried using the interfaces +below. The attribute identifiers are shared with those for key +attributes. @xref{Information about keys}. + +@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_trust_item_get_string_attr} returns the value +of the string-representable attribute @var{what} of trust item +@var{item}. If the attribute occurs more than once in the trust +items, the index is specified by @var{idx}. However, currently no +such attributes exists, so @var{idx} should be @code{0}. The argument +@var{reserved} is reserved for later use and should be @code{NULL}. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun int gpgme_trust_item_get_int_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_trust_item_get_int_attr} returns the value of +the number-representable attribute @var{what} of trust item +@var{item}. If the attribute occurs more than once in the trust item, +the index is specified by @var{idx}. However, currently no such +attribute exists, so @var{idx} should be @code{0}. The argument +@var{reserved} is reserved for later use and should be @code{NULL}. + +The function returns @code{0} if the attribute can't be returned as a +number, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + + +@node Manipulating trust items +@subsection Manipulating trust items + +@deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}}) +The function @code{gpgme_trust_item_release} destroys a +@code{GpgmeTrustItem} object and releases all associated resources. +@end deftypefun + +@node Crypto Operations +@section Crypto Operations + +@menu +* Decrypt:: Decrypting a ciphertext. +* Verify:: Verifying a signature. +* Decrypt and verify:: Decrypting a signed ciphertext. +* Sign:: Creating a signature. +* Encrypt:: Encrypting a plaintext. +@end menu + + +@node Decrypt +@subsection Decrypt + +@deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}) +The function @code{gpgme_op_decrypt} decrypts the ciphertext in the +data object @var{cipher} and stores it into the data object +@var{plain}. + +The function returns @code{GPGME_No_Error} if the ciphertext could be +decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx}, +@var{cipher} or @var{plain} is not a valid pointer, +@code{GPGME_No_Data} if @var{cipher} does not contain any data to +decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid +cipher text, @code{GPGME_No_Passphrase} if the passphrase for the +secret key could not be retrieved, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + +@c @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}) +@c The function @code{gpgme_op_decrypt_start} initiates a +@c @code{gpgme_op_decrypt} operation. It can be completed by calling +@c @code{gpgme_wait} on the context. + +@c The function returns @code{GPGME_No_Error} if the operation could be +@c started, @code{GPGME_Invalid_Value} if @var{cipher} or @var{plain} is +@c not a valid pointer, and passes through any errors that are reported +@c by the crypto engine support routines. +@c @end deftypefun + + +@node Verify +@subsection Verify + +@deftp {Data type} {enum GpgmeSigStat} +The @code{GpgmeSigStat} type holds the result of a signature check, or +the combined result of all signatures. The following results are +possible: + +@table @code +@item GPGME_SIG_STAT_NONE +This status should not occur in normal operation. + +@item GPGME_SIG_STAT_GOOD +This status indicates that the signature is valid. For the combined +result this status means that all signatures are valid. + +@item GPGME_SIG_STAT_BAD +This status indicates that the signature is invalid. For the combined +result this status means that all signatures are invalid. + +@item GPGME_SIG_STAT_NOKEY +This status indicates that the signature could not be verified due to +a missing key. For the combined result this status means that all +signatures could not be checked due to missing keys. + +@item GPGME_SIG_STAT_NOSIG +This status indicates that the signature data provided was not a real +signature. + +@item GPGME_SIG_STAT_ERROR +This status indicates that there was some other error which prevented +the signature verification. + +@item GPGME_SIG_STAT_DIFF +For the combined result this status means that at least two signatures +have a different status. You can get each key's status with +@code{gpgme_get_sig_status}. +@end table +@end deftp + +@deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}}) +The function @code{gpgme_op_verify} verifies that the detached +signature in the data object @var{sig} is a valid signature for the +plaintext in the data object @var{plain}. + +The combined status of all signatures is returned in @var{r_stat}. +The results of the individual signature verifications can be retrieved +with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}. + +The function returns @code{GPGME_No_Error} if the operation could be +completed successfully, @code{GPGME_Invalid_Value} if @var{ctx}, +@var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, +@code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any +data to verify, and passes through any errors that are reported by the +crypto engine support routines. +@end deftypefun + +@c GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig, GpgmeData plain); + +@deftypefun {const char *} gpgme_get_sig_status (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigStat *@var{r_stat}}, @w{time_t *@var{r_created}}) +The function @code{gpgme_get_sig_status} receives information about a +signature after the @code{gpgme_op_verify} or +@code{gpgme_op_verify_decrypt} operation. A single detached signature +can contain signatures by more than one key. The @var{idx} specifies +which signature's information should be retrieved, starting from +@var{0}. + +The status of the signature will be returned in @var{r_stat} if it is +not @code{NULL}. The creation time stamp of the signature will be +returned in @var{r_created} if it is not @var{NULL}. + +The function returns a statically allocated string that contains the +fingerprint of the key which signed the plaintext, or @code{NULL} if +@var{ctx} is not a valid pointer, the operation is still pending, or +no verification could be performed. +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigKey *@var{r_stat}}) +The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey} +object for the key which was used to verify the signature after the +@code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation. A +single detached signature can contain signatures by more than one key. +The @var{idx} specifies which signature's information should be +retrieved, starting from @var{0}. The key will have on reference for +the user. + +The function is a convenient way to retrieve the keys belonging to the +fingerprints returned by @code{gpgme_get_sig_status}. + +The function returns @code{GPGME_No_Error} if the key could be +returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid +pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid, +@code{GPGME_EOF} if @var{idx} is too large, or some other error value +if a problem occured requesting the key. +@end deftypefun + + +@node Decrypt and verify +@subsection Decrypt and verify + +@deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}}) +The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in +the data object @var{cipher} and stores it into the data object +@var{plain}. If @var{cipher} contains signatures, they will be +verified and their combined status will be returned in @var{r_stat}. + +After the operation completed, @code{gpgme_op_get_sig_status} and +@code{gpgme_op_get_sig_key} can be used to retrieve more information +about the signatures. + +The function returns @code{GPGME_No_Error} if the ciphertext could be +decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx}, +@var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, +@code{GPGME_No_Data} if @var{cipher} does not contain any data to +decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid +cipher text, @code{GPGME_No_Passphrase} if the passphrase for the +secret key could not be retrieved, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + +@c GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c, GpgmeData in, GpgmeData out, GpgmeSigStat *r_status); + + +@node Sign +@subsection Sign + +A signature can contain signatures by one or more keys. The set of +keys used to create a signatures is contained in a context, and is +applied to all following signing operations in this context (until the +set is changed). + +@menu +* Selecting signers:: How to choose the keys to sign with. +* Creating a signature:: How to create a signature. +@end menu + + +@node Selecting signers +@subsubsection Selecting signers + +@deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_signers_clear} releases a reference for each +key on the signers list and removes the list of signers from the +context @var{ctx}. + +Every context starts with an empty list. +@end deftypefun + + +@deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}) +The function @code{gpgme_signers_add} adds the key @var{key} to the +list of signers in the context @var{ctx}. + +One reference for the key is consumed. +@end deftypefun + +@deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}}) +The function @code{gpgme_signers_enum} returns the @var{seq}th key in +the list of signers in the context @var{ctx}. An additional reference +is acquired for the user. + +If @var{seq} is out of range, @code{NULL} is returned. +@end deftypefun + + +@node Creating a signature +@subsubsection Creating a signature + +@deftp {Data type} {enum GpgmeSigMode} +The @code{GpgmeSigMode} type is used to specify the desired type of a +signature. The following modes are available: + +@table @code +@item GPGME_SIG_MODE_NORMAL +A normal signature is made, the output includes the plaintext and the +signature. + +@item GPGME_SIG_MODE_DETACH +A detached signature is made. + +@item GPGME_SIG_MODE_CLEAR +A clear text signature is made. The @acronym{ASCII} armor and text +mode settings of the context are ignored. +@end table +@end deftp + +@deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}}) +The function @code{gpgme_op_sign} creates a signature for the text in +the data object @var{plain} and returns it in the data object +@var{sig}. The type of the signature created is determined by the +@acronym{ASCII} and text mode attributes set for the context @var{ctx} +and the requested signature mode @var{mode}. + +The function returns @code{GPGME_No_Error} if the signature could be +created successfully, @code{GPGME_Invalid_Value} if @var{ctx}, +@var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data} +if the signature could not be created, @code{GPGME_No_Passphrase} if +the passphrase for the secret key could not be retrieved, and passes +through any errors that are reported by the crypto engine support +routines. +@end deftypefun + + +@node Encrypt +@subsection Encrypt + +One plaintext can be encrypted for several recipients at the same +time. The list of recipients is created independently of any context, +and then passed to the encryption operation. + +@menu +* Selecting recipients:: How to choose the recipients. +* Encrypting a plaintext:: How to encrypt a plaintext. +@end menu + + +@node Selecting recipients +@subsubsection Selecting recipients + +@deftp {Data type} GpgmeRecipients +The @code{GpgmeRecipients} type is a handle for a set of recipients +that can be used in an encryption process. +@end deftp + +@deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@var{r_rset}}) +The function @code{gpgme_recipients_new} creates a new, empty set of +recipients and returns a handle for it in @var{r_rset}. + +The function returns @code{GPGME_No_Error} if the recipient set could +be created successfully, and @code{GPGME_Out_Of_Core} if not enough +memory was available. +@end deftypefun + +@deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}}) +The function @code{gpgme_recipients_release} destroys the set of +recipients @var{rset} and releases all associated resources. +@end deftypefun + +@deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}) +The function @code{gpgme_recipients_add_name} adds the recipient +@var{name} to the set of recipients @var{rset}. This is equivalent to +@code{gpgme_recipients_add_name_with_validity} with a validity of +@code{GPGME_VALIDITY_UNKNOWN}. + +The function returns @code{GPGME_No_Error} if the recipient was added +successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name} +is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough +memory is available. +@end deftypefun + +@deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @var{val}}) +The function @code{gpgme_recipients_add_name_with_validity} adds the +recipient @var{name} with the validity @var{val} to the set of +recipients @var{rset}. If the validity is not known, the function +@code{gpgme_recipients_add_name} can be used. +@xref{Information about keys}, for the possible values for @var{val}. + +The function returns @code{GPGME_No_Error} if the recipient was added +successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name} +is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough +memory is available. +@end deftypefun + +@deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}}) +The function @code{gpgme_recipients_count} returns the number of +recipients in the set @var{rset}. +@end deftypefun + +@deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}}) +The function @code{gpgme_recipients_enum_open} creates a new iterator +@var{iter} that can be used to walk through the set of recipients in +@var{rset}, using @code{gpgme_recipients_enum_read}. + +If the iterator is not needed anymore, it can be closed with +@code{gpgme_recipients_enum_close}. + +The function returns @code{GPGME_No_Error} if the enumerator was +successfully created and @code{GPGME_Invalid_Value} if @var{rset} or +@var{iter} is not a valid pointer. +@end deftypefun + +@deftypefun {const char *} gpgme_recipients_enum_read (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}}) +The function @code{gpgme_recipients_enum_read} returns a string +containing the name of the next recipient in the set @var{rset} for +the iterator @var{iter}. The string is valid as long as @var{rset} is +valid or the function is called the next time with the same recipient +set and iterator, whatever is earlier. +@end deftypefun + +@deftypefun GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}}) +The function @code{gpgme_recipients_enum_close} releases the iterator +@var{iter} for the recipient set @var{rset}. +@end deftypefun + + +@node Encrypting a plaintext +@subsubsection Encrypting a plaintext + +@deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}}) +The function @code{gpgme_op_crypt} encrypts the plaintext in the data +object @var{plain} for the recipients @var{rset} and stores the +ciphertext in the data object @var{cipher}. The type of the +ciphertext created is determined by the @acronym{ASCII} and text mode +attributes set for the context @var{ctx}. + +The function returns @code{GPGME_No_Error} if the ciphertext could be +created successfully, @code{GPGME_Invalid_Value} if @var{ctx}, +@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, +@code{GPGME_No_Recipient} if @var{rset} does not contain any +valid recipients, @code{GPGME_No_Passphrase} if the passphrase for the +secret key could not be retrieved, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + + +@include gpl.texi + + +@include fdl.texi + + +@node Concept Index +@unnumbered Concept Index + +@printindex cp + + +@node Function and Data Index +@unnumbered Function and Data Index + +@printindex fn + + +@summarycontents +@contents +@bye diff --git a/doc/gpl.texi b/doc/gpl.texi new file mode 100644 index 00000000..ca0508fa --- /dev/null +++ b/doc/gpl.texi @@ -0,0 +1,397 @@ +@node Copying +@appendix GNU GENERAL PUBLIC LICENSE + +@cindex GPL, GNU General Public License +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@appendixsubsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@appendixsubsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and an idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program; if not, write to the Free Software Foundation, Inc., +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. This is free software, and you are welcome +to redistribute it under certain conditions; type `show c' +for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@smallexample +@group +Yoyodyne, Inc., hereby disclaims all copyright +interest in the program `Gnomovision' +(which makes passes at compilers) written +by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end group +@end smallexample + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License.