GpgFrontend/gpgme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc/

Browse Source 
2002-01-30  Marcus Brinkmann  <marcus@g10code.de>

	* gpgme.texi: Add all the gpgme_op_*_start functions.
	Fill the concept index with many, many entries.

gpgme/
2002-01-30  Marcus Brinkmann  <marcus@g10code.de>

	* gpgme.h: Add lots of comment and fix the formatting.  Add
	gpgme_trustlist_end prototype.
This commit is contained in:
Marcus Brinkmann 2002-01-30 01:17:30 +00:00
parent 89dd219f8d
commit 785991aa9a
4 changed files with 638 additions and 227 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/ChangeLog
View File

@ -1,3 +1,8 @@
2002-01-30 Marcus Brinkmann <marcus@g10code.de>
* gpgme.texi: Add all the gpgme_op_*_start functions.
Fill the concept index with many, many entries.
2002-01-29 Marcus Brinkmann <marcus@g10code.de> 2002-01-29 Marcus Brinkmann <marcus@g10code.de>
* gpgme.texi (Run Control): New section. * gpgme.texi (Run Control): New section.

248
doc/gpgme.texi
View File

@ -165,7 +165,7 @@ Crypto Operations
* Decrypt and Verify:: Decrypting a signed ciphertext. * Decrypt and Verify:: Decrypting a signed ciphertext.
* Sign:: Creating a signature. * Sign:: Creating a signature.
* Encrypt:: Encrypting a plaintext. * Encrypt:: Encrypting a plaintext.
* More Information:: How to obtain more info about the operation. * Detailed Results:: How to obtain more info about the operation.
Sign Sign
@ -213,7 +213,7 @@ This library documents the @acronym{GPGME} library programming
interface. All functions and data types provided by the library are interface. All functions and data types provided by the library are
explained. explained.
The reader is assumed to posess basic knowledge about cryptography in The reader is assumed to possess basic knowledge about cryptography in
general, and public key cryptography in particular. The underlying general, and public key cryptography in particular. The underlying
cryptographic engines that are used by the library are not explained, cryptographic engines that are used by the library are not explained,
but where necessary, special features or requirements by an engine are but where necessary, special features or requirements by an engine are
@ -277,6 +277,8 @@ including listing keys, querying their attributes, generating,
importing, exporting and deleting keys, and acquiring information importing, exporting and deleting keys, and acquiring information
about the trust path. about the trust path.
@cindex thread-safeness
@cindex multi-threading
@strong{Caution:} The @acronym{GPGME} library is not thread-safe. It @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 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. be taken if @acronym{GPGME} is used in a multi-threaded environment.
@ -300,6 +302,8 @@ of the library are verified.
@node Header @node Header
@section Header @section Header
@cindex header file
@cindex include file
All interfaces (data types and functions) of the library are defined All interfaces (data types and functions) of the library are defined
in the header file `gpgme.h'. You must include this in all programs in the header file `gpgme.h'. You must include this in all programs
@ -317,6 +321,8 @@ symbols.
@node Building the Source @node Building the Source
@section Building the Source @section Building the Source
@cindex compiler options
@cindex compiler flags
If you want to compile a source file including the `gpgme.h' header 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 file, you must make sure that the compiler can find it in the
@ -364,6 +370,7 @@ gcc -o foo foo.c `gpgme-config --cflags --libs`
@node Library Version Check @node Library Version Check
@section Library Version Check @section Library Version Check
@cindex version check, of the library
@deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}}) @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
The function @code{gpgme_check_version} has three purposes. It can be The function @code{gpgme_check_version} has three purposes. It can be
@ -396,6 +403,11 @@ features are provided by the installed version of the library.
@node Protocols and Engines @node Protocols and Engines
@chapter Protocols and Engines @chapter Protocols and Engines
@cindex protocol
@cindex engine
@cindex crypto engine
@cindex backend
@cindex crypto backend
@acronym{GPGME} supports several cryptographic protocols, however, it @acronym{GPGME} supports several cryptographic protocols, however, it
does not implement them. Rather it uses backends (also called does not implement them. Rather it uses backends (also called
@ -409,6 +421,7 @@ necessary, @acronym{GPGME} provides the necessary callback function
hooks and further interfaces. hooks and further interfaces.
@deftp {Data type} {enum GpgmeProtocol} @deftp {Data type} {enum GpgmeProtocol}
@tindex GpgmeProtocol
The @code{GpgmeProtocol} type specifies the set of possible protocol The @code{GpgmeProtocol} type specifies the set of possible protocol
values that are supported by @acronym{GPGME}. The following protocols values that are supported by @acronym{GPGME}. The following protocols
are supported: are supported:
@ -431,6 +444,7 @@ This specifies the Cryptographic Message Syntax.
@node Engine Version Check @node Engine Version Check
@section Engine Version Check @section Engine Version Check
@cindex version check, of the engines
@deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}}) @deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
The function @code{gpgme_engine_check_version} verifies that the The function @code{gpgme_engine_check_version} verifies that the
@ -455,6 +469,7 @@ only. It is obsoleted by @code{gpgme_engine_check_version}.
@node Engine Information @node Engine Information
@section Engine Information @section Engine Information
@cindex engine, information about
@deftypefun {const char *} gpgme_get_engine_info (void) @deftypefun {const char *} gpgme_get_engine_info (void)
The function @code{gpgme_get_engine_info} returns an @acronym{XML} The function @code{gpgme_get_engine_info} returns an @acronym{XML}
@ -496,6 +511,10 @@ return on your system:
@node OpenPGP @node OpenPGP
@section OpenPGP @section OpenPGP
@cindex OpenPGP
@cindex GnuPG
@cindex protocol, GnuPG
@cindex engine, GnuPG
OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard. OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
This is the first protocol that was supported by @acronym{GPGME}. This is the first protocol that was supported by @acronym{GPGME}.
@ -505,6 +524,13 @@ The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
@node Cryptographic Message Syntax @node Cryptographic Message Syntax
@section Cryptographic Message Syntax @section Cryptographic Message Syntax
@cindex CMS
@cindex cryptographic message syntax
@cindex GpgSM
@cindex protocol, CMS
@cindex engine, GpgSM
@cindex S/MIME
@cindex protocol, S/MIME
@acronym{CMS} is implemented by GpgSM, the S/MIME implementation for @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
GnuPG. GnuPG.
@ -514,6 +540,7 @@ The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
@node Error Handling @node Error Handling
@chapter Error Handling @chapter Error Handling
@cindex error handling
Many functions in @acronym{GPGME} can return an error if they fail. Many functions in @acronym{GPGME} can return an error if they fail.
For this reason, the application should always catch the error For this reason, the application should always catch the error
@ -538,8 +565,10 @@ described in the documentation of those functions.
@node Error Values @node Error Values
@section Error Values @section Error Values
@cindex error values, list of
@deftp {Data type} {enum GpgmeError} @deftp {Data type} {enum GpgmeError}
@tindex GpgmeError
The @code{GpgmeError} type specifies the set of all error values that The @code{GpgmeError} type specifies the set of all error values that
are used by @acronym{GPGME}. Possible values are: are used by @acronym{GPGME}. Possible values are:
@ -644,6 +673,8 @@ engine is not installed properly.
@node Error Strings @node Error Strings
@section Error Strings @section Error Strings
@cindex error values, printing of
@cindex error strings
@deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}}) @deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
The function @code{gpgme_strerror} returns a pointer to a statically The function @code{gpgme_strerror} returns a pointer to a statically
@ -655,6 +686,7 @@ message to the user.
@node Exchanging Data @node Exchanging Data
@chapter Exchanging Data @chapter Exchanging Data
@cindex data, exchanging
A lot of data has to be exchanged between the user and the crypto A lot of data has to be exchanged between the user and the crypto
engine, like plaintext messages, ciphertext, signatures and engine, like plaintext messages, ciphertext, signatures and
@ -678,6 +710,7 @@ data, which is used by @acronym{GPGME} to exchange data with the user.
@node Creating Data Buffers @node Creating Data Buffers
@section Creating Data Buffers @section Creating Data Buffers
@cindex data buffer, creation
@deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}}) @deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
The function @code{gpgme_data_new} creates a new @code{GpgmeData} The function @code{gpgme_data_new} creates a new @code{GpgmeData}
@ -768,6 +801,7 @@ not enough memory is available.
@node Destroying Data Buffers @node Destroying Data Buffers
@section Destroying Data Buffers @section Destroying Data Buffers
@cindex data buffer, destruction
@deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}}) @deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
The function @code{gpgme_data_release} destroys the data object with The function @code{gpgme_data_release} destroys the data object with
@ -791,6 +825,7 @@ be returned to the user, the function will return @code{NULL}.
@node Manipulating Data Buffers @node Manipulating Data Buffers
@section Manipulating Data Buffers @section Manipulating Data Buffers
@cindex data buffere, manipulation
@deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}}) @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 The function @code{gpgme_data_read} reads up to @var{length} bytes
@ -836,6 +871,7 @@ available.
@end deftypefun @end deftypefun
@deftp {Data type} {enum GpgmeDataType} @deftp {Data type} {enum GpgmeDataType}
@tindex GpgmeDataType
The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object. The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object.
The following data types are available: The following data types are available:
@ -867,6 +903,7 @@ object with the handle @var{dh}. If @var{dh} is not a valid pointer,
@node Contexts @node Contexts
@chapter Contexts @chapter Contexts
@cindex context
All cryptograhic operations in @acronym{GPGME} are performed within a All cryptograhic operations in @acronym{GPGME} are performed within a
context, which contains the internal state of the operation as well as context, which contains the internal state of the operation as well as
@ -893,6 +930,7 @@ cryptographic operations.
@node Creating Contexts @node Creating Contexts
@section Creating Contexts @section Creating Contexts
@cindex context, creation
@deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}}) @deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
The function @code{gpgme_data_new} creates a new @code{GpgmeCtx} The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
@ -905,9 +943,9 @@ available.
@end deftypefun @end deftypefun
@node Destroying Contexts @node Destroying Contexts
@section Destroying Contexts @section Destroying Contexts
@cindex context, destruction
@deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}}) @deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
The function @code{gpgme_release} destroys the context with the handle The function @code{gpgme_release} destroys the context with the handle
@ -917,6 +955,7 @@ The function @code{gpgme_release} destroys the context with the handle
@node Context Attributes @node Context Attributes
@section Context Attributes @section Context Attributes
@cindex context, attributes
@menu @menu
* Protocol Selection:: Selecting the protocol used by a context. * Protocol Selection:: Selecting the protocol used by a context.
@ -930,6 +969,8 @@ The function @code{gpgme_release} destroys the context with the handle
@node Protocol Selection @node Protocol Selection
@subsection Protocol Selection @subsection Protocol Selection
@cindex context, selecting protocol
@cindex protocol, selecting
@deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}}) @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 function @code{gpgme_set_protocol} sets the protocol used within
@ -949,6 +990,9 @@ not a valid protocol.
@node @acronym{ASCII} Armor @node @acronym{ASCII} Armor
@subsection @acronym{ASCII} Armor @subsection @acronym{ASCII} Armor
@cindex context, armor mode
@cindex @acronym{ASCII} armor
@cindex armor mode
@deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}}) @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 The function @code{gpgme_set_armor} specifies if the output should be
@ -968,6 +1012,9 @@ not a valid pointer.
@node Text Mode @node Text Mode
@subsection Text Mode @subsection Text Mode
@cindex context, text mode
@cindex text mode
@cindex canonical text mode
@deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}}) @deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
The function @code{gpgme_set_textmode} specifies if canonical text mode The function @code{gpgme_set_textmode} specifies if canonical text mode
@ -990,6 +1037,8 @@ valid pointer.
@node Key Listing Mode @node Key Listing Mode
@subsection Key Listing Mode @subsection Key Listing Mode
@cindex key listing mode
@cindex key listing, mode of
@deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{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 The function @code{gpgme_set_keylist_mode} changes the default
@ -1007,8 +1056,11 @@ Fast listing without information about the key validity.
@node Passphrase Callback @node Passphrase Callback
@subsection Passphrase Callback @subsection Passphrase Callback
@cindex callback, passphrase
@cindex passphrase callback
@deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})} @deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})}
@tindex GpgmePassphraseCb
The @code{GpgmePasshraseCb} type is the type of functions usable as The @code{GpgmePasshraseCb} type is the type of functions usable as
passphrase callback function. passphrase callback function.
@ -1044,8 +1096,11 @@ calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
@node Progress Meter Callback @node Progress Meter Callback
@subsection Progress Meter Callback @subsection Progress Meter Callback
@cindex callback, progress meter
@cindex 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})} @deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
@tindex GpgmeProgressCb
The @code{GpgmeProgressCb} type is the type of functions usable as The @code{GpgmeProgressCb} type is the type of functions usable as
progress callback function. progress callback function.
@ -1074,6 +1129,7 @@ calling @code{gpgme_set_progress_cb} with @var{progfunc} being
@node Key Management @node Key Management
@section Key Management @section Key Management
@cindex key management
Some of the cryptographic operations require that recipients or Some of the cryptographic operations require that recipients or
signers are specified. This is always done by specifying the signers are specified. This is always done by specifying the
@ -1100,6 +1156,11 @@ A key can contain several user IDs and sub keys.
@node Listing Keys @node Listing Keys
@subsection Listing Keys @subsection Listing Keys
@cindex listing keys
@cindex key listing
@cindex key listing, start
@cindex key ring, list
@cindex key ring, search
@deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}}) @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 The function @code{gpgme_op_keylist_start} initiates a key listing
@ -1154,6 +1215,9 @@ operation there was not enough memory available.
@node Information About Keys @node Information About Keys
@subsection Information About Keys @subsection Information About Keys
@cindex key, information about
@cindex key, attributes
@cindex attributes, of a key
@deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}}) @deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
The function @code{gpgme_key_get_as_xml} returns a string in The function @code{gpgme_key_get_as_xml} returns a string in
@ -1344,6 +1408,7 @@ or @var{reserved} not @code{NULL}.
@node Manipulating Keys @node Manipulating Keys
@subsection Manipulating Keys @subsection Manipulating Keys
@cindex key, manipulation
@deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}}) @deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
The function @code{gpgme_key_ref} acquires an additional reference for The function @code{gpgme_key_ref} acquires an additional reference for
@ -1363,6 +1428,8 @@ The function @code{gpgme_key_release} is an alias for
@node Generating Keys @node Generating Keys
@subsection Generating Keys @subsection Generating Keys
@cindex key, creation
@cindex key ring, add
@deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}}) @deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
The function @code{gpgme_op_genkey} generates a new key pair in the The function @code{gpgme_op_genkey} generates a new key pair in the
@ -1377,7 +1444,7 @@ implemented yet).
The argument @var{parms} specifies parameters for the key in an XML The argument @var{parms} specifies parameters for the key in an XML
string. The details about the format of @var{parms} are specific to string. The details about the format of @var{parms} are specific to
teh crypto engine used by @var{ctx}. Here is an example for GnuPG as the crypto engine used by @var{ctx}. Here is an example for GnuPG as
the crypto engine: the crypto engine:
@example @example
@ -1404,14 +1471,27 @@ container is passed verbatim to GnuPG. Control statements are not
allowed. allowed.
The function returns @code{GPGME_No_Error} if the operation could be The function returns @code{GPGME_No_Error} if the operation could be
started, @code{GPGME_Invalid_Value} if @var{parms} is not a valid XML started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
string, and @code{GPGME_Not_Supported} if @var{pubkey} or @var{seckey} a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
is not @code{NULL}. @var{seckey} is not @code{NULL}.
@end deftypefun
@deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
The function @code{gpgme_op_genkey_start} initiates a
@code{gpgme_op_genkey} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
@var{seckey} is not @code{NULL}.
@end deftypefun @end deftypefun
@node Exporting Keys @node Exporting Keys
@subsection Exporting Keys @subsection Exporting Keys
@cindex key, export
@cindex key ring, export from
@deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}}) @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
The function @code{gpgme_op_export} extracts the public keys of the The function @code{gpgme_op_export} extracts the public keys of the
@ -1426,9 +1506,22 @@ passes through any errors that are reported by the crypto engine
support routines. support routines.
@end deftypefun @end deftypefun
@deftypefun GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
The function @code{gpgme_op_export_start} initiates a
@code{gpgme_op_export} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, and @code{GPGME_Invalid_Value} if
@var{recipients} is @code{NULL} or @var{keydata} is not a valid empty
data buffer.
@end deftypefun
@node Importing Keys @node Importing Keys
@subsection Importing Keys @subsection Importing Keys
@cindex key, import
@cindex key ring, import to
@deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}}) @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
The function @code{gpgme_op_import} adds the keys in the data buffer The function @code{gpgme_op_import} adds the keys in the data buffer
@ -1442,9 +1535,22 @@ or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
@var{keydata} is an empty data buffer. @var{keydata} is an empty data buffer.
@end deftypefun @end deftypefun
@deftypefun GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
The function @code{gpgme_op_import_start} initiates a
@code{gpgme_op_import} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the import could be
started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if
@var{ctx} or @var{keydata} is not a valid pointer, and
@code{GPGME_No_Data} if @var{keydata} is an empty data buffer.
@end deftypefun
@node Deleting Keys @node Deleting Keys
@subsection Deleting Keys @subsection Deleting Keys
@cindex key, delete
@cindex key ring, delete from
@deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}}) @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
The function @code{gpgme_op_delete} deletes the key @var{key} from the The function @code{gpgme_op_delete} deletes the key @var{key} from the
@ -1457,9 +1563,20 @@ successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or @var{key}
is not a valid pointer. is not a valid pointer.
@end deftypefun @end deftypefun
@deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
The function @code{gpgme_op_delete_start} initiates a
@code{gpgme_op_delete} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the operation was
started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
@var{key} is not a valid pointer.
@end deftypefun
@node Trust Item Management @node Trust Item Management
@section Trust Item Management @section Trust Item Management
@cindex trust item
@strong{Caution:} The trust items interface is experimental. @strong{Caution:} The trust items interface is experimental.
@ -1476,6 +1593,7 @@ The @code{GpgmeTrustItem} type is a handle for a trust item.
@node Listing Trust Items @node Listing Trust Items
@subsection Listing Trust Items @subsection Listing Trust Items
@cindex trust item list
@deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}}) @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 The function @code{gpgme_op_trustlist_start} initiates a trust item
@ -1529,6 +1647,9 @@ operation there was not enough memory available.
@node Information About Trust Items @node Information About Trust Items
@subsection Information About Trust Items @subsection Information About Trust Items
@cindex trust item, information about
@cindex trust item, attributes
@cindex attributes, of a trust item
Trust items have attributes which can be queried using the interfaces Trust items have attributes which can be queried using the interfaces
below. The attribute identifiers are shared with those for key below. The attribute identifiers are shared with those for key
@ -1565,6 +1686,7 @@ or @var{reserved} not @code{NULL}.
@node Manipulating Trust Items @node Manipulating Trust Items
@subsection Manipulating Trust Items @subsection Manipulating Trust Items
@cindex trust item, manipulation
@deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}}) @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
The function @code{gpgme_trust_item_release} destroys a The function @code{gpgme_trust_item_release} destroys a
@ -1573,6 +1695,7 @@ The function @code{gpgme_trust_item_release} destroys a
@node Crypto Operations @node Crypto Operations
@section Crypto Operations @section Crypto Operations
@cindex cryptographic operation
@menu @menu
* Decrypt:: Decrypting a ciphertext. * Decrypt:: Decrypting a ciphertext.
@ -1580,12 +1703,14 @@ The function @code{gpgme_trust_item_release} destroys a
* Decrypt and Verify:: Decrypting a signed ciphertext. * Decrypt and Verify:: Decrypting a signed ciphertext.
* Sign:: Creating a signature. * Sign:: Creating a signature.
* Encrypt:: Encrypting a plaintext. * Encrypt:: Encrypting a plaintext.
* More Information:: How to obtain more info about the operation. * Detailed Results:: How to obtain more info about the operation.
@end menu @end menu
@node Decrypt @node Decrypt
@subsection Decrypt @subsection Decrypt
@cindex decryption
@cindex cryptographic operation, decryption
@deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}) @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 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
@ -1602,22 +1727,27 @@ secret key could not be retrieved, and passes through any errors that
are reported by the crypto engine support routines. are reported by the crypto engine support routines.
@end deftypefun @end deftypefun
@c @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}) @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 The function @code{gpgme_op_decrypt_start} initiates a
@c @code{gpgme_op_decrypt} operation. It can be completed by calling @code{gpgme_op_decrypt} operation. It can be completed by calling
@c @code{gpgme_wait} on the context. @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
@c The function returns @code{GPGME_No_Error} if the operation could be 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 started successfully, and @code{GPGME_Invalid_Value} if @var{cipher}
@c not a valid pointer, and passes through any errors that are reported or @var{plain} is not a valid pointer.
@c by the crypto engine support routines. @end deftypefun
@c @end deftypefun
@node Verify @node Verify
@subsection Verify @subsection Verify
@cindex verification
@cindex signature, verification
@cindex cryptographic operation, verification
@cindex cryptographic operation, signature check
@cindex signature, status
@deftp {Data type} {enum GpgmeSigStat} @deftp {Data type} {enum GpgmeSigStat}
@tindex GpgmeSigStat
The @code{GpgmeSigStat} type holds the result of a signature check, or The @code{GpgmeSigStat} type holds the result of a signature check, or
the combined result of all signatures. The following results are the combined result of all signatures. The following results are
possible: possible:
@ -1671,7 +1801,17 @@ data to verify, and passes through any errors that are reported by the
crypto engine support routines. crypto engine support routines.
@end deftypefun @end deftypefun
@c GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig, GpgmeData plain); @deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}})
The function @code{gpgme_op_verify_start} initiates a
@code{gpgme_op_verify} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and
@code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
data to verify.
@end deftypefun
@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}}) @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 The function @code{gpgme_get_sig_status} receives information about a
@ -1727,6 +1867,10 @@ The function returns a string if the notation data is available or
@node Decrypt and Verify @node Decrypt and Verify
@subsection Decrypt and Verify @subsection Decrypt and Verify
@cindex decryption and verification
@cindex verification and decryption
@cindex signature check
@cindex cryptographic operation, decryption and verification
@deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}}) @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 function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
@ -1748,11 +1892,25 @@ secret key could not be retrieved, and passes through any errors that
are reported by the crypto engine support routines. are reported by the crypto engine support routines.
@end deftypefun @end deftypefun
@c GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c, GpgmeData in, GpgmeData out, GpgmeSigStat *r_status); @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
The function @code{gpgme_op_decrypt_verify_start} initiates a
@code{gpgme_op_decrypt_verify} operation. It can be completed by
calling @code{gpgme_wait} on the context. @xref{Waiting For
Completion}.
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and
@code{GPGME_No_Data} if @var{cipher} does not contain any data to
decrypt.
@end deftypefun
@node Sign @node Sign
@subsection Sign @subsection Sign
@cindex signature, creation
@cindex sign
@cindex cryptographic operation, signing
A signature can contain signatures by one or more keys. The set of 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 keys used to create a signatures is contained in a context, and is
@ -1767,6 +1925,8 @@ set is changed).
@node Selecting Signers @node Selecting Signers
@subsubsection Selecting Signers @subsubsection Selecting Signers
@cindex signature, selecting signers
@cindex signers, selecting
@deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}}) @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
The function @code{gpgme_signers_clear} releases a reference for each The function @code{gpgme_signers_clear} releases a reference for each
@ -1776,7 +1936,6 @@ context @var{ctx}.
Every context starts with an empty list. Every context starts with an empty list.
@end deftypefun @end deftypefun
@deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}) @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 The function @code{gpgme_signers_add} adds the key @var{key} to the
list of signers in the context @var{ctx}. list of signers in the context @var{ctx}.
@ -1797,6 +1956,7 @@ If @var{seq} is out of range, @code{NULL} is returned.
@subsubsection Creating a Signature @subsubsection Creating a Signature
@deftp {Data type} {enum GpgmeSigMode} @deftp {Data type} {enum GpgmeSigMode}
@tindex GpgmeSigMode
The @code{GpgmeSigMode} type is used to specify the desired type of a The @code{GpgmeSigMode} type is used to specify the desired type of a
signature. The following modes are available: signature. The following modes are available:
@ -1822,7 +1982,7 @@ the data object @var{plain} and returns it in the data object
@var{ctx} and the requested signature mode @var{mode}. @var{ctx} and the requested signature mode @var{mode}.
More information about the signatures is available with More information about the signatures is available with
@code{gpgme_get_op_info}. @xref{More Information}. @code{gpgme_get_op_info}. @xref{Detailed Results}.
The function returns @code{GPGME_No_Error} if the signature could be The function returns @code{GPGME_No_Error} if the signature could be
created successfully, @code{GPGME_Invalid_Value} if @var{ctx}, created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@ -1833,9 +1993,21 @@ through any errors that are reported by the crypto engine support
routines. routines.
@end deftypefun @end deftypefun
@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_start} initiates a
@code{gpgme_op_sign} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
@var{plain} or @var{sig} is not a valid pointer.
@end deftypefun
@node Encrypt @node Encrypt
@subsection Encrypt @subsection Encrypt
@cindex encryption
@cindex cryptographic operation, encryption
One plaintext can be encrypted for several recipients at the same One plaintext can be encrypted for several recipients at the same
time. The list of recipients is created independently of any context, time. The list of recipients is created independently of any context,
@ -1849,6 +2021,8 @@ and then passed to the encryption operation.
@node Selecting Recipients @node Selecting Recipients
@subsubsection Selecting Recipients @subsubsection Selecting Recipients
@cindex encryption, selecting recipients
@cindex recipients
@deftp {Data type} GpgmeRecipients @deftp {Data type} GpgmeRecipients
The @code{GpgmeRecipients} type is a handle for a set of recipients The @code{GpgmeRecipients} type is a handle for a set of recipients
@ -1937,7 +2111,7 @@ ciphertext created is determined by the @acronym{ASCII} armor and text
mode attributes set for the context @var{ctx}. mode attributes set for the context @var{ctx}.
More information about the encrypted text is available with More information about the encrypted text is available with
@code{gpgme_get_op_info}. @xref{More Information}. @code{gpgme_get_op_info}. @xref{Detailed Results}.
The function returns @code{GPGME_No_Error} if the ciphertext could be The function returns @code{GPGME_No_Error} if the ciphertext could be
created successfully, @code{GPGME_Invalid_Value} if @var{ctx}, created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@ -1948,11 +2122,24 @@ secret key could not be retrieved, and passes through any errors that
are reported by the crypto engine support routines. are reported by the crypto engine support routines.
@end deftypefun @end deftypefun
@deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
The function @code{gpgme_op_encrypt_start} initiates a
@code{gpgme_op_encrypt} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
@node More Information The function returns @code{GPGME_No_Error} if the operation could be
@subsection More Information started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
@code{GPGME_No_Recipient} if @var{rset} does not contain any valid
recipients.
@end deftypefun
@deftypefun char *gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
@node Detailed Results
@subsection Detailed Results
@cindex cryptographic operation, detailed results
@deftypefun {char *} gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
The function @code{gpgme_get_op_info} retrieves more informaton about The function @code{gpgme_get_op_info} retrieves more informaton about
the last crypto operation. the last crypto operation.
@ -1988,6 +2175,8 @@ available.
@node Run Control @node Run Control
@section Run Control @section Run Control
@cindex run control
@cindex cryptographic operation, running
Some basic support for running operations asynchronously is available Some basic support for running operations asynchronously is available
in @acronym{GPGME}. You can use it to set up a context completely up in @acronym{GPGME}. You can use it to set up a context completely up
@ -2003,6 +2192,8 @@ later point.
@node Waiting For Completion @node Waiting For Completion
@subsection Waiting For Completion @subsection Waiting For Completion
@cindex cryptographic operation, wait for
@cindex wait for completion
@deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{int @var{hang}}) @deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{int @var{hang}})
The function @code{gpgme_wait} does continue the pending operation The function @code{gpgme_wait} does continue the pending operation
@ -2020,6 +2211,8 @@ The function returns @var{ctx}.
@node Cancelling an Operation @node Cancelling an Operation
@subsection Cancelling an Operation @subsection Cancelling an Operation
@cindex cancellation
@cindex cryptographic operation, cancel
@deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}}) @deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}})
The function @code{gpgme_cancel} tries to cancel the pending The function @code{gpgme_cancel} tries to cancel the pending
@ -2032,8 +2225,11 @@ asking for a passphrase again in the passphrase callback.
@node Hooking Up Into Idle Time @node Hooking Up Into Idle Time
@subsection Hooking Up Into Idle Time @subsection Hooking Up Into Idle Time
@cindex idle time
@cindex idle function
@deftp {Data type} {void (*GpgmeIdleFnc) (void)} @deftp {Data type} {void (*GpgmeIdleFunc) (void)}
@tindex GpgmeIdleFunc
The @code{GpgmeIdleFunc} type is the type of functions usable as The @code{GpgmeIdleFunc} type is the type of functions usable as
an idle function that can be registered with @code{gpgme_register_idle}. an idle function that can be registered with @code{gpgme_register_idle}.
@end deftp @end deftp

5
gpgme/ChangeLog
View File

@ -1,3 +1,8 @@
2002-01-30 Marcus Brinkmann <marcus@g10code.de>
* gpgme.h: Add lots of comment and fix the formatting. Add
gpgme_trustlist_end prototype.
2002-01-29 Marcus Brinkmann <marcus@g10code.de> 2002-01-29 Marcus Brinkmann <marcus@g10code.de>
* gpgme.h: Add new type GpgmeIdleFunc. Change type of * gpgme.h: Add new type GpgmeIdleFunc. Change type of

403
gpgme/gpgme.h
View File

@ -22,7 +22,7 @@
#ifndef GPGME_H #ifndef GPGME_H
#define GPGME_H #define GPGME_H
#include <stdio.h> /* for FILE * */ #include <stdio.h> /* For FILE *. */
#ifdef _MSC_VER #ifdef _MSC_VER
typedef long off_t; typedef long off_t;
#else #else
@ -37,34 +37,42 @@ extern "C" {
#endif #endif
/* /* The version of this header should match the one of the library. Do
* The version of this header should match the one of the library not use this symbol in your application, use gpgme_check_version
* It should not be used by a program because gpgme_check_version(NULL) instead. The purpose of this macro is to let autoconf (using the
* does return the same version. The purpose of this macro is to AM_PATH_GPGME macro) check that this header matches the installed
* let autoconf (using the AM_PATH_GPGME macro) check that this library. Warning: Do not edit the next line. configure will do
* header matches the installed library. that for you! */
* Warning: Do not edit the next line. configure will do that for you! */
#define GPGME_VERSION "0.3.0a-cvs" #define GPGME_VERSION "0.3.0a-cvs"
/* The opaque data types used by GPGME. */
/* The context holds some global state and configration options as
well as the results of a crypto operation. */
struct gpgme_context_s; struct gpgme_context_s;
typedef struct gpgme_context_s *GpgmeCtx; typedef struct gpgme_context_s *GpgmeCtx;
/* The data object used by GPGME to exchange arbitrary data. */
struct gpgme_data_s; struct gpgme_data_s;
typedef struct gpgme_data_s *GpgmeData; typedef struct gpgme_data_s *GpgmeData;
/* A list of recipients to be used in an encryption operation. */
struct gpgme_recipients_s; struct gpgme_recipients_s;
typedef struct gpgme_recipients_s *GpgmeRecipients; typedef struct gpgme_recipients_s *GpgmeRecipients;
/* A key from the keyring. */
struct gpgme_key_s; struct gpgme_key_s;
typedef struct gpgme_key_s *GpgmeKey; typedef struct gpgme_key_s *GpgmeKey;
/* A trust item. */
struct gpgme_trust_item_s; struct gpgme_trust_item_s;
typedef struct gpgme_trust_item_s *GpgmeTrustItem; typedef struct gpgme_trust_item_s *GpgmeTrustItem;
typedef enum { /* The error numbers used by GPGME. */
typedef enum
{
GPGME_EOF = -1, GPGME_EOF = -1,
GPGME_No_Error = 0, GPGME_No_Error = 0,
GPGME_General_Error = 1, GPGME_General_Error = 1,
@ -83,23 +91,29 @@ typedef enum {
GPGME_Write_Error = 14, GPGME_Write_Error = 14,
GPGME_Invalid_Type = 15, GPGME_Invalid_Type = 15,
GPGME_Invalid_Mode = 16, GPGME_Invalid_Mode = 16,
GPGME_File_Error = 17, /* errno is set in this case */ GPGME_File_Error = 17, /* errno is set in this case. */
GPGME_Decryption_Failed = 18, GPGME_Decryption_Failed = 18,
GPGME_No_Passphrase = 19, GPGME_No_Passphrase = 19,
GPGME_Canceled = 20, GPGME_Canceled = 20,
GPGME_Invalid_Key = 21, GPGME_Invalid_Key = 21,
GPGME_Invalid_Engine = 22 GPGME_Invalid_Engine = 22
} GpgmeError; }
GpgmeError;
typedef enum { /* The possible types of GpgmeData objects. */
typedef enum
{
GPGME_DATA_TYPE_NONE = 0, GPGME_DATA_TYPE_NONE = 0,
GPGME_DATA_TYPE_MEM = 1, GPGME_DATA_TYPE_MEM = 1,
GPGME_DATA_TYPE_FD = 2, GPGME_DATA_TYPE_FD = 2,
GPGME_DATA_TYPE_FILE = 3, GPGME_DATA_TYPE_FILE = 3,
GPGME_DATA_TYPE_CB = 4 GPGME_DATA_TYPE_CB = 4
} GpgmeDataType; }
GpgmeDataType;
typedef enum { /* The possible signature stati. */
typedef enum
{
GPGME_SIG_STAT_NONE = 0, GPGME_SIG_STAT_NONE = 0,
GPGME_SIG_STAT_GOOD = 1, GPGME_SIG_STAT_GOOD = 1,
GPGME_SIG_STAT_BAD = 2, GPGME_SIG_STAT_BAD = 2,
@ -107,15 +121,21 @@ typedef enum {
GPGME_SIG_STAT_NOSIG = 4, GPGME_SIG_STAT_NOSIG = 4,
GPGME_SIG_STAT_ERROR = 5, GPGME_SIG_STAT_ERROR = 5,
GPGME_SIG_STAT_DIFF = 6 GPGME_SIG_STAT_DIFF = 6
} GpgmeSigStat; }
GpgmeSigStat;
typedef enum { /* The available signature modes. */
typedef enum
{
GPGME_SIG_MODE_NORMAL = 0, GPGME_SIG_MODE_NORMAL = 0,
GPGME_SIG_MODE_DETACH = 1, GPGME_SIG_MODE_DETACH = 1,
GPGME_SIG_MODE_CLEAR = 2 GPGME_SIG_MODE_CLEAR = 2
} GpgmeSigMode; }
GpgmeSigMode;
typedef enum { /* The available key attributes. */
typedef enum
{
GPGME_ATTR_KEYID = 1, GPGME_ATTR_KEYID = 1,
GPGME_ATTR_FPR = 2, GPGME_ATTR_FPR = 2,
GPGME_ATTR_ALGO = 3, GPGME_ATTR_ALGO = 3,
@ -141,183 +161,368 @@ typedef enum {
GPGME_ATTR_CAN_CERTIFY = 23, GPGME_ATTR_CAN_CERTIFY = 23,
GPGME_ATTR_KEY_EXPIRED = 24, GPGME_ATTR_KEY_EXPIRED = 24,
GPGME_ATTR_KEY_DISABLED = 25 GPGME_ATTR_KEY_DISABLED = 25
} GpgmeAttr; }
GpgmeAttr;
typedef enum { /* The available validities for a trust item or key. */
typedef enum
{
GPGME_VALIDITY_UNKNOWN = 0, GPGME_VALIDITY_UNKNOWN = 0,
GPGME_VALIDITY_UNDEFINED = 1, GPGME_VALIDITY_UNDEFINED = 1,
GPGME_VALIDITY_NEVER = 2, GPGME_VALIDITY_NEVER = 2,
GPGME_VALIDITY_MARGINAL = 3, GPGME_VALIDITY_MARGINAL = 3,
GPGME_VALIDITY_FULL = 4, GPGME_VALIDITY_FULL = 4,
GPGME_VALIDITY_ULTIMATE = 5 GPGME_VALIDITY_ULTIMATE = 5
} GpgmeValidity; }
GpgmeValidity;
/* The available protocols. */
typedef enum { typedef enum
GPGME_PROTOCOL_OpenPGP = 0, /* default */ {
GPGME_PROTOCOL_OpenPGP = 0, /* The default mode. */
GPGME_PROTOCOL_CMS = 1, GPGME_PROTOCOL_CMS = 1,
GPGME_PROTOCOL_AUTO = 2 GPGME_PROTOCOL_AUTO = 2
} GpgmeProtocol; }
GpgmeProtocol;
typedef const char *(*GpgmePassphraseCb)(void*,
const char *desc, void **r_hd); /* Types for callback functions. */
typedef void (*GpgmeProgressCb)(void *opaque,
const char *what, /* Request a passphrase from the user. */
typedef const char *(*GpgmePassphraseCb) (void *hook, const char *desc,
void **r_hd);
/* Inform the user about progress made. */
typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
int type, int current, int total); int type, int current, int total);
/* Context management */
GpgmeError gpgme_new (GpgmeCtx *r_ctx);
void gpgme_release (GpgmeCtx c);
void gpgme_cancel (GpgmeCtx c);
GpgmeCtx gpgme_wait (GpgmeCtx c, int hang);
char *gpgme_get_notation (GpgmeCtx c); /* Context management functions. */
GpgmeError gpgme_set_protocol (GpgmeCtx c, GpgmeProtocol prot);
void gpgme_set_armor (GpgmeCtx c, int yes);
int gpgme_get_armor (GpgmeCtx c);
void gpgme_set_textmode (GpgmeCtx c, int yes);
int gpgme_get_textmode (GpgmeCtx c);
void gpgme_set_keylist_mode ( GpgmeCtx c, int mode );
void gpgme_set_passphrase_cb (GpgmeCtx c,
GpgmePassphraseCb cb, void *cb_value);
void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *cb_value);
void gpgme_signers_clear (GpgmeCtx c); /* Create a new context and return it in CTX. */
GpgmeError gpgme_signers_add (GpgmeCtx c, const GpgmeKey key); GpgmeError gpgme_new (GpgmeCtx *ctx);
GpgmeKey gpgme_signers_enum (const GpgmeCtx c, int seq);
const char *gpgme_get_sig_status (GpgmeCtx c, int idx, /* Release the context CTX. */
void gpgme_release (GpgmeCtx ctx);
/* Retrieve more info about performed signature check. */
char *gpgme_get_notation (GpgmeCtx ctx);
/* Set the protocol to be used by CTX to PROTO. */
GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
/* If YES is non-zero, enable armor mode in CTX, disable it otherwise. */
void gpgme_set_armor (GpgmeCtx ctx, int yes);
/* Return non-zero if armor mode is set in CTX. */
int gpgme_get_armor (GpgmeCtx ctx);
/* If YES is non-zero, enable text mode in CTX, disable it otherwise. */
void gpgme_set_textmode (GpgmeCtx ctx, int yes);
/* Return non-zero if text mode is set in CTX. */
int gpgme_get_textmode (GpgmeCtx ctx);
/* Set keylist mode in CTX to MODE. */
void gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
/* Set the passphrase callback function in CTX to CB. HOOK_VALUE is
passed as first argument to the passphrase callback function. */
void gpgme_set_passphrase_cb (GpgmeCtx ctx,
GpgmePassphraseCb cb, void *hook_value);
/* Set the progress callback function in CTX to CB. HOOK_VALUE is
passed as first argument to the progress callback function. */
void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
/* Delete all signers from CTX. */
void gpgme_signers_clear (GpgmeCtx ctx);
/* Add KEY to list of signers in CTX. */
GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
/* Return the SEQth signer's key in CTX. */
GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
/* Retrieve the signature status of signature IDX in CTX after a
successful verify operation in R_STAT (if non-null). The creation
time stamp of the signature is returned in R_CREATED (if non-null).
The function returns a string containing the fingerprint. */
const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
GpgmeSigStat *r_stat, time_t *r_created); GpgmeSigStat *r_stat, time_t *r_created);
GpgmeError gpgme_get_sig_key (GpgmeCtx c, int idx, GpgmeKey *r_key);
char *gpgme_get_op_info (GpgmeCtx c, int reserved); /* Get the key used to create signature IDX in CTX and return it in
R_KEY. */
GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
/* Return a string with more info about the last crypto operating in CTX.
RESERVED should be zero. The user has to free the string. */
char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
/* Functions to handle recipients */ /* Run control. */
/* Cancel a pending operation in CTX. */
void gpgme_cancel (GpgmeCtx ctx);
/* Process the pending operation and, if HANG is non-zero, wait for
the pending operation to finish. */
GpgmeCtx gpgme_wait (GpgmeCtx ctx, int hang);
/* Functions to handle recipients. */
/* Create a new recipients set and return it in R_RSET. */
GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset); GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
/* Release the recipients set RSET. */
void gpgme_recipients_release (GpgmeRecipients rset); void gpgme_recipients_release (GpgmeRecipients rset);
GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset,
const char *name); /* Add NAME to the recipients set RSET. */
GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
/* Add NAME with validity AL to the recipients set RSET. */
GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset, GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
const char *name, const char *name,
GpgmeValidity val); GpgmeValidity val);
/* Return the number of recipients in RSET. */
unsigned int gpgme_recipients_count (const GpgmeRecipients rset); unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,void **ctx);
const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,void **ctx); /* Create a new enumeration handle for the recipients set RSET and
GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,void **ctx); return it in ITER. */
GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
void **iter);
/* Return the next recipient from the recipient set RSET in the
enumerator ITER. */
const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
void **iter);
/* Destroy the enumerator ITER for the recipient set RSET. */
GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
void **iter);
/* Functions to handle data sources */ /* Functions to handle data objects. */
/* Create a new data buffer and return it in R_DH. */
GpgmeError gpgme_data_new (GpgmeData *r_dh); GpgmeError gpgme_data_new (GpgmeData *r_dh);
/* Create a new data buffer filled with SIZE bytes starting from
BUFFER. If COPY is zero, copying is delayed until necessary, and
the data is taken from the original location when needed. */
GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh, GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
const char *buffer, size_t size, const char *buffer, size_t size,
int copy); int copy);
/* Create a new data buffer which retrieves the data from the callback
function READ_CB. */
GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh, GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
int (*read_cb) (void*,char *,size_t,size_t*), int (*read_cb) (void*,char *,size_t,size_t*),
void *read_cb_value); void *read_cb_value);
/* Create a new data buffer filled with the content of file FNAME.
COPY must be non-zero (delayed reads are not supported yet). */
GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh, GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
const char *fname, const char *fname,
int copy); int copy);
/* Create a new data buffer filled with LENGTH bytes starting from
OFFSET within the file FNAME or stream FP (exactly one must be
non-zero). */
GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh, GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
const char *fname, FILE *fp, const char *fname, FILE *fp,
off_t offset, size_t length); off_t offset, size_t length);
/* Destroy the data buffer DH. */
void gpgme_data_release (GpgmeData dh); void gpgme_data_release (GpgmeData dh);
/* Destroy the data buffer DH and return a pointer to its content.
The memory has be to released with free by the user. It's size is
returned in R_LEN. */
char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len); char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
/* Return the type of the data buffer DH. */
GpgmeDataType gpgme_data_get_type (GpgmeData dh); GpgmeDataType gpgme_data_get_type (GpgmeData dh);
/* Reset the read pointer in DH. */
GpgmeError gpgme_data_rewind (GpgmeData dh); GpgmeError gpgme_data_rewind (GpgmeData dh);
GpgmeError gpgme_data_read ( GpgmeData dh,
char *buffer, size_t length, size_t *nread ); /* Read LENGTH bytes from the data object DH and store them in the
GpgmeError gpgme_data_write ( GpgmeData dh, memory starting at BUFFER. The number of bytes actually read is
const char *buffer, size_t length ); returned in NREAD. */
GpgmeError gpgme_data_read (GpgmeData dh, char *buffer,
size_t length, size_t *nread);
/* Write LENGTH bytes starting from BUFFER into the data object DH. */
GpgmeError gpgme_data_write (GpgmeData dh, const char *buffer, size_t length);
/* Key and trust functions */ /* Key and trust functions. */
/* Acquire a reference to KEY. */
void gpgme_key_ref (GpgmeKey key); void gpgme_key_ref (GpgmeKey key);
/* Release a reference to KEY. If this was the last one the key is
destroyed. */
void gpgme_key_unref (GpgmeKey key); void gpgme_key_unref (GpgmeKey key);
void gpgme_key_release (GpgmeKey key); void gpgme_key_release (GpgmeKey key);
/* Get the data from key KEY in a XML string, which has to be released
with free by the user. */
char *gpgme_key_get_as_xml (GpgmeKey key); char *gpgme_key_get_as_xml (GpgmeKey key);
/* Return the value of the attribute WHAT of KEY, which has to be
representable by a string. IDX specifies a running index if the
attribute appears more than once in the key. */
const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what, const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
const void *reserved, int idx); const void *reserved, int idx);
/* Return the value of the attribute WHAT of KEY, which has to be
representable by an unsigned integer. IDX specifies a running
index if the attribute appears more than once in the key. */
unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what, unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
const void *reserved, int idx); const void *reserved, int idx);
/* Release the trust item ITEM. */
void gpgme_trust_item_release (GpgmeTrustItem item); void gpgme_trust_item_release (GpgmeTrustItem item);
/* Return the value of the attribute WHAT of ITEM, which has to be
representable by a string. IDX specifies a running index if the
attribute appears more than once in the key. */
const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item, const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
GpgmeAttr what, GpgmeAttr what,
const void *reserved, int idx); const void *reserved, int idx);
/* Return the value of the attribute WHAT of KEY, which has to be
representable by an integer. IDX specifies a running index if the
attribute appears more than once in the key. */
int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what, int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
const void *reserved, int idx); const void *reserved, int idx);
/* Crypto operation function. */
/* Encrypt plaintext PLAIN within CTX for the recipients RECP and
/* Basic GnuPG functions */ store the resulting ciphertext in CIPHER. */
GpgmeError gpgme_op_encrypt_start ( GpgmeCtx c, GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
GpgmeRecipients recp, GpgmeRecipients recp,
GpgmeData in, GpgmeData out ); GpgmeData plain, GpgmeData cipher);
GpgmeError gpgme_op_decrypt_start ( GpgmeCtx c, GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
GpgmeData ciph, GpgmeData plain ); GpgmeRecipients recp,
GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx c, GpgmeData plain, GpgmeData cipher);
GpgmeData ciph, GpgmeData plain);
GpgmeError gpgme_op_sign_start ( GpgmeCtx c, /* Decrypt ciphertext CIPHER within CTX and store the resulting
GpgmeData in, GpgmeData out, plaintext in PLAIN. */
GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
GpgmeData cipher, GpgmeData plain);
GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
GpgmeData cipher, GpgmeData plain);
/* Decrypt ciphertext CIPHER and make a signature verification within
CTX and store the resulting plaintext in PLAIN. */
GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
GpgmeData cipher, GpgmeData plain);
GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
GpgmeData cipher, GpgmeData plain,
GpgmeSigStat *r_status);
/* Sign the plaintext PLAIN and store the signature in SIG. Only
detached signatures are supported for now. */
GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
GpgmeData plain, GpgmeData sig,
GpgmeSigMode mode); GpgmeSigMode mode);
GpgmeError gpgme_op_verify_start ( GpgmeCtx c, GpgmeError gpgme_op_sign (GpgmeCtx ctx,
GpgmeData plain, GpgmeData sig,
GpgmeSigMode mode);
/* Verify within CTX that SIG is a valid signature for TEXT. */
GpgmeError gpgme_op_verify_start (GpgmeCtx ctx,
GpgmeData sig, GpgmeData text); GpgmeData sig, GpgmeData text);
GpgmeError gpgme_op_import_start ( GpgmeCtx c, GpgmeData keydata ); GpgmeError gpgme_op_verify (GpgmeCtx ctx,
GpgmeError gpgme_op_export_start ( GpgmeCtx c, GpgmeRecipients recp, GpgmeData sig, GpgmeData text,
GpgmeSigStat *r_status);
/* Import the key in KEYDATA into the keyring. */
GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
/* Export the keys listed in RECP into KEYDATA. */
GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
GpgmeData keydata); GpgmeData keydata);
GpgmeError gpgme_op_genkey_start ( GpgmeCtx c, const char *parms, GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
GpgmeData keydata);
/* Generate a new keypair and add it to the keyring. PUBKEY and
SECKEY should be null for now. PARMS specifies what keys should be
generated. */
GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
GpgmeData pubkey, GpgmeData seckey); GpgmeData pubkey, GpgmeData seckey);
GpgmeError gpgme_op_delete_start ( GpgmeCtx c, const GpgmeKey key, GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
GpgmeData pubkey, GpgmeData seckey);
/* Delete KEY from the keyring. If ALLOW_SECRET is non-zero, secret
keys are also deleted. */
GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
int allow_secret);
GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
int allow_secret); int allow_secret);
/* Key management functions */ /* Key management functions */
/* Start a keylist operation within CTX, searching for keys which
match PATTERN. If SECRET_ONLY is true, only secret keys are
returned. */
GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx, GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
const char *pattern, int secret_only); const char *pattern, int secret_only);
/* Return the next key from the keylist in R_KEY. */
GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key); GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
/* Terminate a pending keylist operation within CTX. */
GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx); GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
/* Start a trustlist operation within CTX, searching for trust items
which match PATTERN. */
GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx, GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
const char *pattern, int max_level); const char *pattern, int max_level);
/* Return the next trust item from the trustlist in R_ITEM. */
GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item); GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
/* Terminate a pending trustlist operation within CTX. */
GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
/* Convenience functions for normal usage */ /* Various functions. */
GpgmeError gpgme_op_encrypt ( GpgmeCtx c, GpgmeRecipients recp,
GpgmeData in, GpgmeData out );
GpgmeError gpgme_op_decrypt ( GpgmeCtx c,
GpgmeData in, GpgmeData out );
GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c,
GpgmeData in, GpgmeData out,
GpgmeSigStat *r_status);
GpgmeError gpgme_op_sign ( GpgmeCtx c, GpgmeData in, GpgmeData out,
GpgmeSigMode mode);
GpgmeError gpgme_op_verify ( GpgmeCtx c, GpgmeData sig, GpgmeData text,
GpgmeSigStat *r_status );
GpgmeError gpgme_op_import ( GpgmeCtx c, GpgmeData keydata );
GpgmeError gpgme_op_export ( GpgmeCtx c, GpgmeRecipients recp,
GpgmeData keydata );
GpgmeError gpgme_op_genkey ( GpgmeCtx c, const char *parms,
GpgmeData pubkey, GpgmeData seckey );
GpgmeError gpgme_op_delete ( GpgmeCtx c, const GpgmeKey key, int allow_secret);
/* Check that the library fulfills the version requirement. */
/* miscellaneous functions */
const char *gpgme_check_version (const char *req_version); const char *gpgme_check_version (const char *req_version);
/* Check that the backend engine is available. DEPRECATED. */
GpgmeError gpgme_check_engine (void); GpgmeError gpgme_check_engine (void);
/* Retrieve information about the backend engines. */
const char *gpgme_get_engine_info (void); const char *gpgme_get_engine_info (void);
/* Return a string describing ERR. */
const char *gpgme_strerror (GpgmeError err); const char *gpgme_strerror (GpgmeError err);
/* Register an idle function. */
typedef void (*GpgmeIdleFunc)(void); typedef void (*GpgmeIdleFunc)(void);
GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle); GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
/* Engine support functions. */ /* Engine support functions. */
/* Verify that the engine implementing PROTO is installed and
available. */
GpgmeError gpgme_engine_check_version (GpgmeProtocol proto); GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif