@value{VERSION}.
@c NOTE: Don't forget to update the year for the TeX version, too.
-Copyright @copyright{} 2002, 2003, 2004 g10 Code GmbH.
+Copyright @copyright{} 2002, 2003, 2004, 2005 g10 Code GmbH.
The GPGME reference manual 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.
+and/or modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either version
+2.1 of the License, or (at your option) any later version.
The GPGME reference manual 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.
+Lesser General Public License for more details.
-You should have received a copy of the GNU General Public License
-along with this manual; if not, write to the Free Software Foundation,
-Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
+You should have received a copy of the GNU Lesser 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 ifinfo
@center for version @value{VERSION}
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 2002, 2003, 2004 g10 Code GmbH.
+Copyright @copyright{} 2002, 2003, 2004, 2005 g10 Code GmbH.
+
The GPGME reference manual 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.
+and/or modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either version
+2.1 of the License, or (at your option) any later version.
The GPGME reference manual 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.
+Lesser General Public License for more details.
-You should have received a copy of the GNU General Public License
-along with this manual; if not, write to the Free Software Foundation,
-Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
+You should have received a copy of the GNU Lesser 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 titlepage
@page
Appendices
-* Copying:: The GNU General Public License says how you
- can copy and share `GnuPG Made Easy'.
+* Library Copying:: The GNU Lesser General Public License says
+ how you can copy and share `GnuPG Made Easy'.
Indices
* Engine Version Check:: Verifying the engine version.
* Engine Information:: Obtaining more information about the engines.
+* Engine Configuration:: Changing the engine configuration.
* OpenPGP:: Support for the OpenPGP protocol.
* Cryptographic Message Syntax:: Support for the CMS.
* File Based Data Buffers:: Creating file based data buffers.
* Callback Based Data Buffers:: Creating callback based data buffers.
+Manipulating Data Buffers
+
+* Data Buffer I/O Operations:: I/O operations on data buffers.
+* Data Buffer Meta-Data:: Meta-data manipulation of data buffers.
+
Contexts
* Creating Contexts:: Creating new @acronym{GPGME} contexts.
Context Attributes
* Protocol Selection:: Selecting the protocol used by a context.
+* Crypto Engine:: Configuring the crypto engine.
* ASCII Armor:: Requesting @acronym{ASCII} armored output.
* Text Mode:: Choosing canonical text mode.
* Included Certificates:: Including a number of certificates.
* Selecting Signers:: How to choose the keys to sign with.
* Creating a Signature:: How to create a signature.
+* Signature Notation Data:: How to add notation data to a signature.
Encrypt
@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}).
+Lesser General Public License (@pxref{Library Copying}).
@item it's flexible
@acronym{GPGME} provides transparent support for several cryptographic
@end deftp
-@deftypefun const char *gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}})
+@deftypefun {const char *} gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}})
The function @code{gpgme_get_protocol_name} returns a statically
allocated string describing the protocol @var{protocol}, or
@code{NULL} if the protocol number is not valid.
@menu
* Engine Version Check:: Verifying the engine version.
* Engine Information:: Obtaining more information about the engines.
+* Engine Configuration:: Changing the engine configuration.
* OpenPGP:: Support for the OpenPGP protocol.
* Cryptographic Message Syntax:: Support for the CMS.
@end menu
engine. Currently, it is never @code{NULL}, but using @code{NULL} is
reserved for future use, so always check before you use it.
+@item const char *home_dir
+This is a string holding the directory name of the crypto engine's
+configuration directory. If it is @code{NULL}, then the default
+directory is used.
+
@item const char *version
This is a string containing the version number of the crypto engine.
It might be @code{NULL} if the version number can not be determined,
@end table
@end deftp
-@deftypefun gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *info)
+@deftypefun gpgme_error_t gpgme_get_engine_info (@w{gpgme_engine_info_t *@var{info}})
The function @code{gpgme_get_engine_info} returns a linked list of
engine info structures in @var{info}. Each info structure describes
-one configured backend.
+the defaults of one configured backend.
The memory for the info structures is allocated the first time this
function is invoked, and must not be freed by the caller.
@end example
+@node Engine Configuration
+@section Engine Configuration
+@cindex engine, configuration of
+@cindex configuration of crypto backend
+
+You can change the configuration of a backend engine, and thus change
+the executable program and configuration directory to be used. You
+can make these changes the default or set them for some contexts
+individually.
+
+@deftypefun gpgme_error_t gpgme_set_engine_info (@w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
+The function @code{gpgme_set_engine_info} changes the default
+configuration of the crypto engine implementing the protocol
+@var{proto}.
+
+@var{file_name} is the file name of the executable program
+implementing this protocol, and @var{home_dir} is the directory name
+of the configuration directory for this crypto engine. If
+@var{home_dir} is @code{NULL}, the engine's default will be used.
+
+The new defaults are not applied to already created GPGME contexts.
+
+This function returns the error code @code{GPG_ERR_NO_ERROR} if
+successful, or an eror code on failure.
+@end deftypefun
+
+The functions @code{gpgme_ctx_get_engine_info} and
+@code{gpgme_ctx_set_engine_info} can be used to change the engine
+configuration per context. @xref{Crypto Engine}.
+
+
@node OpenPGP
@section OpenPGP
@cindex OpenPGP
@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.
+The user has to release the buffer with @code{gpgme_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
+@deftypefun void gpgme_free (@w{void *@var{buffer}})
+The function @code{gpgme_free} releases the memory returned by
+@code{gpgme_data_release_and_get_mem}. It should be used instead of
+the system libraries @code{free} function in case different allocators
+are used in a single program.
+@end deftypefun
+
+
@node Manipulating Data Buffers
@section Manipulating Data Buffers
-@cindex data buffere, manipulation
+@cindex data buffer, manipulation
+
+Data buffers contain data and meta-data. The following operations can
+be used to manipulate both.
+
+
+@menu
+* Data Buffer I/O Operations:: I/O operations on data buffers.
+* Data Buffer Meta-Data:: Meta-data manipulation of data buffers.
+@end menu
+
+
+@node Data Buffer I/O Operations
+@subsection Data Buffer I/O Operations
+@cindex data buffer, I/O operations
+@cindex data buffer, read
+@cindex data buffer, write
+@cindex data buffer, seek
@deftypefun ssize_t gpgme_data_read (@w{gpgme_data_t @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}})
The function @code{gpgme_data_read} reads up to @var{length} bytes
@end example
@end deftypefun
-@c
-@c gpgme_data_encoding_t
-@c
+
+
+
+@node Data Buffer Meta-Data
+@subsection Data Buffer Meta-Data
+@cindex data buffer, meta-data
+@cindex data buffer, file name
+@cindex data buffer, encoding
+
+@deftypefun {char *} gpgme_data_get_file_name (@w{gpgme_data_t @var{dh}})
+The function @code{gpgme_data_get_file_name} returns a pointer to a
+string containing the file name associated with the data object. The
+file name will be stored in the output when encrypting or signing the
+data and will be returned to the user when decrypting or verifying the
+output data.
+
+If no error occurs, the string containing the file name is returned.
+Otherwise, @code{NULL} will be returned.
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_data_set_file_name (@w{gpgme_data_t @var{dh}}, @w{const char *@var{file_name}})
+The function @code{gpgme_data_set_file_name} sets the file name
+associated with the data object. The file name will be stored in the
+output when encrypting or signing the data and will be returned to the
+user when decrypting or verifying the output data.
+
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{dh} is not a valid pointer and @code{GPG_ERR_ENOMEM} if not
+enough memory is available.
+@end deftypefun
+
+
@deftp {Data type} {enum gpgme_data_encoding_t}
@tindex gpgme_data_encoding_t
The @code{gpgme_data_encoding_t} type specifies the encoding of a
@menu
* Protocol Selection:: Selecting the protocol used by a context.
+* Crypto Engine:: Configuring the crypto engine.
* ASCII Armor:: Requesting @acronym{ASCII} armored output.
* Text Mode:: Choosing canonical text mode.
* Included Certificates:: Including a number of certificates.
use with the context @var{ctx}.
@end deftypefun
+
+@node Crypto Engine
+@subsection Crypto Engine
+@cindex context, configuring engine
+@cindex engine, configuration per context
+
+The following functions can be used to set and retrieve the
+configuration of the crypto engines of a specific context. The
+default can also be retrieved without any particular context.
+@xref{Engine Information}. The default can also be changed globally.
+@xref{Engine Configuration}.
+
+@deftypefun gpgme_engine_info_t gpgme_ctx_get_engine_info (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_ctx_get_engine_info} returns a linked list of
+engine info structures. Each info structure describes the
+configuration of one configured backend, as used by the context
+@var{ctx}.
+
+The result is valid until the next invocation of
+@code{gpgme_ctx_set_engine_info} for this particular context.
+
+This function can not fail.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_ctx_set_engine_info (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
+The function @code{gpgme_ctx_set_engine_info} changes the
+configuration of the crypto engine implementing the protocol
+@var{proto} for the context @var{ctx}.
+
+@var{file_name} is the file name of the executable program
+implementing this protocol, and @var{home_dir} is the directory name
+of the configuration directory for this crypto engine. If
+@var{home_dir} is @code{NULL}, the engine's default will be used.
+
+Currently this function must be used before starting the first crypto
+operation. It is unspecified if and when the changes will take effect
+if the function is called after starting the first operation on the
+context @var{ctx}.
+
+This function returns the error code @code{GPG_ERR_NO_ERROR} if
+successful, or an eror code on failure.
+@end deftypefun
+
+
@c FIXME: Unfortunately, using @acronym here breaks texi2dvi.
@node ASCII Armor
@subsection @acronym{ASCII} Armor
values of @var{nr_of_certs} are:
@table @code
+@item GPGME_INCLUDE_CERTS_DEFAULT
+Fall back to the default of the crypto backend. This is the default
+for GPGME.
@item -2
Include all certificates except the root certificate.
@item -1
@cindex key listing mode
@cindex key listing, mode of
-@deftypefun void gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
+@deftypefun gpgme_error_t gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
The function @code{gpgme_set_keylist_mode} changes the default
behaviour of the key listing functions. The value in @var{mode} is a
bitwise-or combination of one or multiple of the following bit values:
The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
signatures should be included in the listed keys.
+@item GPGME_KEYLIST_MODE_SIG_NOTATIONS
+The @code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} symbol specifies that the
+signature notations on key signatures should be included in the listed
+keys. This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also
+enabled.
+
@item GPGME_KEYLIST_MODE_VALIDATE
The @code{GPGME_KEYLIST_MODE_VALIDATE} symbol specifies that the
backend should do key or certificate validation and not just get the
validity information from an internal cache. This might be an
-expensive operation and is in general not usefule. Currently only
+expensive operation and is in general not useful. Currently only
implemented for the S/MIME backend and ignored for other backends.
@end table
@item unsigned int can_authenticate : 1
This is true if the subkey can be used for authentication.
+@item unsigned int is_qualified : 1
+This is true if the subkey can be used for qualified signatures
+according to local government regulations.
+
@item unsigned int secret : 1
-This is true if the subkey is a secret key.
+This is true if the subkey is a secret key. Note that it will be false
+if the key is actually a stub key; i.e. a secret key operation is
+currently not possible (offline-key).
@item gpgme_pubkey_algo_t pubkey_algo
This is the public key algorithm supported by this subkey.
@item char *fpr
This is the fingerprint of the subkey in hexadecimal digits, if
-available. This is usually only available for the primary key.
+available.
@item long int timestamp
This is the creation timestamp of the subkey. This is -1 if the
The signatures on a key are only available if the key was retrieved
via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
-enabled, because it is expensive to retrieve all signatures of a key.
+enabled, because it can be expensive to retrieve all signatures of a
+key.
+
+The signature notations on a key signature are only available if the
+key was retrieved via a listing operation with the
+@code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} mode enabled, because it can
+be expensive to retrieve all signature notations.
The key signature structure has the following members:
@item char *email
This is the email component of @code{uid}, if available.
+
+@item gpgme_sig_notation_t notations
+This is a linked list with the notation data and policy URLs.
@end table
@end deftp
This is true if the key (ie one of its subkeys) can be used for
authentication.
+@item unsigned int is_qualified : 1
+This is true if the key can be used for qualified signatures according
+to local government regulations.
+
@item unsigned int secret : 1
-This is true if the key is a secret key.
+This is true if the key is a secret key. Note, that this will always be
+true even if the corresponding subkey flag may be false (offline/stub
+keys).
@item gpgme_protocol_t protocol
This is the protocol supported by this key.
if @var{cipher} or @var{plain} is not a valid pointer.
@end deftypefun
+@deftp {Data type} {gpgme_recipient_t}
+This is a pointer to a structure used to store information about the
+recipient of an encrypted text which is decrypted in a
+@code{gpgme_op_decrypt} operation. This information (except for the
+status field) is even available before the operation finished
+successfully, for example in a passphrase callback. The structure
+contains the following members:
+
+@table @code
+@item gpgme_recipient_t next
+This is a pointer to the next recipient structure in the linked list,
+or @code{NULL} if this is the last element.
+
+@item gpgme_pubkey_algo_t
+The public key algorithm used in the encryption.
+
+@item unsigned int wrong_key_usage : 1
+This is true if the key was not used according to its policy.
+
+@item char *keyid
+This is the key ID of the key (in hexadecimal digits) used as
+recipient.
+
+@item gpgme_error_t status
+This is an error number with the error code GPG_ERR_NO_SECKEY if the
+secret key for this recipient is not available, and 0 otherwise.
+@end table
+@end deftp
+
@deftp {Data type} {gpgme_decrypt_result_t}
This is a pointer to a structure used to store the result of a
-@code{gpgme_op_decrypt} operation. After successfully encrypting
+@code{gpgme_op_decrypt} operation. After successfully decrypting
data, you can retrieve the pointer to the result with
@code{gpgme_op_decrypt_result}. The structure contains the following
members:
@item unsigned int wrong_key_usage : 1
This is true if the key was not used according to its policy.
+
+@item gpgme_recipient_t recipient
+This is a linked list of recipients to which this message was encrypted.
+
+@item char *file_name
+This is the filename of the original plaintext message file if it is
+known, otherwise this is a null pointer.
@end table
@end deftp
@cindex signature, verification
@cindex cryptographic operation, verification
@cindex cryptographic operation, signature check
+@cindex signature notation data
+@cindex notation data
@deftypefun gpgme_error_t gpgme_op_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
The function @code{gpgme_op_verify} verifies that the signature in the
The name of the notation field. If this is @code{NULL}, then the
member @code{value} will contain a policy URL.
+@item int name_len
+The length of the @code{name} field. For strings the length is
+counted without the trailing binary zero.
+
@item char *value
The value of the notation field. If @code{name} is @code{NULL}, then
this is a policy URL.
+
+@item int value_len
+The length of the @code{value} field. For strings the length is
+counted without the trailing binary zero.
+
+@item gpgme_sig_notation_flags_t flags
+The accumulated flags field. This field contains the flags associated
+with the notation data in an accumulated form which can be used as an
+argument to the function @code{gpgme_sig_notation_add}. The value
+@code{flags} is a bitwise-or combination of one or multiple of the
+following bit values:
+
+@table @code
+@item GPGME_SIG_NOTATION_HUMAN_READABLE
+The @code{GPGME_SIG_NOTATION_HUMAN_READABLE} symbol specifies that the
+notation data is in human readable form
+
+@item GPGME_SIG_NOTATION_CRITICAL
+The @code{GPGME_SIG_NOTATION_CRITICAL} symbol specifies that the
+notation data is critical.
+
+@end table
+
+@item unsigned int human_readable : 1
+This is true if the @code{GPGME_SIG_NOTATION_HUMAN_READABLE} flag is
+set and false otherwise. This flag is only valid for notation data,
+not for policy URLs.
+
+@item unsigned int critical : 1
+This is true if the @code{GPGME_SIG_NOTATION_CRITICAL} flag is set and
+false otherwise. This flag is valid for notation data and policy URLs.
+
@end table
@end deftp
@item gpgme_error_t validity_reason
If a signature is not valid, this provides a reason why.
+@item gpgme_pubkey_algo_t
+The public key algorithm used to create this signature.
+
+@item gpgme_hash_algo_t
+The hash algorithm used to create this signature.
@end table
@end deftp
@item gpgme_signature_t signatures
A linked list with information about all signatures for which a
verification was attempted.
+
+@item char *file_name
+This is the filename of the original plaintext message file if it is
+known, otherwise this is a null pointer.
@end table
@end deftp
@menu
* Selecting Signers:: How to choose the keys to sign with.
* Creating a Signature:: How to create a signature.
+* Signature Notation Data:: How to add notation data to a signature.
@end menu
@end deftypefun
+@node Signature Notation Data
+@subsubsection Signature Notation Data
+@cindex notation data
+@cindex signature notation data
+@cindex policy URL
+
+Using the following functions, you can attach arbitrary notation data
+to a signature. This information is then available to the user when
+the signature is verified.
+
+@deftypefun void gpgme_sig_notation_clear (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_sig_notation_clear} removes the notation data
+from the context @var{ctx}. Subsequent signing operations from this
+context will not include any notation data.
+
+Every context starts with an empty notation data list.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_sig_notation_add (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{name}}, @w{const char *@var{value}}, @w{gpgme_sig_notation_flags_t @var{flags}})
+The function @code{gpgme_sig_notation_add} adds the notation data with
+the name @var{name} and the value @var{value} to the context
+@var{ctx}.
+
+Subsequent signing operations will include this notation data, as well
+as any other notation data that was added since the creation of the
+context or the last @code{gpgme_sig_notation_clear} operation.
+
+The arguments @var{name} and @var{value} must be @code{NUL}-terminated
+strings in human-readable form. The flag
+@code{GPGME_SIG_NOTATION_HUMAN_READABLE} is implied
+(non-human-readable notation data is currently not supported). The
+strings must be in UTF-8 encoding.
+
+If @var{name} is @code{NULL}, then @var{value} should be a policy URL.
+
+The function @code{gpgme_sig_notation_add} returns the error code
+@code{GPG_ERR_NO_ERROR} if the notation data could be added
+successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} is not a valid
+pointer, or if @var{name}, @var{value} and @var{flags} are an invalid
+combination. The function also passes through any errors that are
+reported by the crypto engine support routines.
+@end deftypefun
+
+@deftypefun gpgme_sig_notation_t gpgme_sig_notation_get (@w{const gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_sig_notation_get} returns the linked list of
+notation data structures that are contained in the context @var{ctx}.
+
+If @var{ctx} is not a valid pointer, or there is no notation data
+added for this context, @code{NULL} is returned.
+@end deftypefun
+
+
@node Encrypt
@subsection Encrypt
@cindex encryption
callback functions. Usually this is done in an event loop, that also
checks for events in other parts of the program. If the callback
functions are only called when the file descriptors are ready,
-@acronym{GPGME} will never block. This gives the user mroe control
+@acronym{GPGME} will never block. This gives the user more control
over the program flow, and allows to perform other tasks when
@acronym{GPGME} would block otherwise.
@deftp {Data type} {gpgme_error_t (*gpgme_register_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{gpgme_io_cb_t @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})}
@tindex gpgme_register_io_cb_t
The @code{gpgme_register_io_cb_t} type is the type of functions which can
-be called by @acronym{GPGME} to register an I/O callback funtion
+be called by @acronym{GPGME} to register an I/O callback function
@var{fnc} for the file descriptor @var{fd} with the user.
@var{fnc_data} should be passed as the first argument to @var{fnc}
when the handler is invoked (the second argument should be @var{fd}).
@end deftypefun
-@include gpl.texi
+@include lesser.texi
@node Concept Index
projects / gpgme.git / blobdiff