[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All cryptographic operations in 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.
GpgmeCtx
type is a handle for a GPGME context,
which is used to hold the configuration, status and result of
cryptographic operations.
6.1 Creating Contexts Creating new GPGME contexts. 6.2 Destroying Contexts Releasing GPGME contexts. 6.3 Context Attributes Setting properties of a context. 6.4 Key Management Managing keys with GPGME. 6.5 Trust Item Management Managing trust items with GPGME. 6.6 Crypto Operations Using a context for cryptography. 6.7 Run Control Controlling how operations are run.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_data_new
creates a new GpgmeCtx
object and returns a handle for it in ctx.
The function returns GPGME_No_Error
if the context was
successfully created, GPGME_Invalid_Value
if ctx is not a
valid pointer, and GPGME_Out_Of_Core
if not enough memory is
available.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_release
destroys the context with the handle
ctx and releases all associated resources.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
6.3.1 Protocol Selection Selecting the protocol used by a context. 6.3.2 ASCII Armor Requesting ASCII armored output. 6.3.3 Text Mode Choosing canonical text mode. 6.3.4 Included Certificates Including a number of certificates. 6.3.5 Key Listing Mode Selecting key listing mode. 6.3.6 Passphrase Callback Getting the passphrase from the user. 6.3.7 Progress Meter Callback Being informed about the progress.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_set_protocol
sets the protocol used within
the context ctx to proto. All crypto operations will be
performed by the crypto engine configured for that protocol.
See section 3. Protocols and Engines.
Setting the protocol with gpgme_set_protocol
does not check if
the crypto engine for that protocol is available and installed
correctly. See section 3.1 Engine Version Check.
The function returns GPGME_No_Error
if the protocol could be
set successfully, and GPGME_Invalid_Value
if protocol is
not a valid protocol.
gpgme_get_protocol
retrieves the protocol currently
use with the context ctx.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_set_armor
specifies if the output should be
ASCII armored. By default, output is not ASCII
armored.
ASCII armored output is disabled if yes is zero, and enabled otherwise.
gpgme_get_armor
returns 1 if the output is
ASCII armored, and 0
if it is not, or if ctx is
not a valid pointer.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
This option is only relevant to the OpenPGP crypto engine, and ignored by all other engines.
Canonical text mode is disabled if yes is zero, and enabled otherwise.
gpgme_get_textmode
returns 1 if canonical text
mode is enabled, and 0
if it is not, or if ctx is not a
valid pointer.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_set_include_certs
specifies how many
certificates should be included in an S/MIME signed message. By
default, only the sender's certificate is included. The possible
values of nr_of_certs are:
-2
-1
0
1
n
n
must be positive.
Values of nr_of_certs smaller than -2 are undefined.
This option is only relevant to the CMS crypto engine, and ignored by all other engines.
gpgme_get_include_certs
returns the number of
certificates to include into an S/MIME signed message.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_set_keylist_mode
changes the default
behaviour of the key listing functions. The value in mode is a
bitwise-or combination of one or multiple of the following bit values:
GPGME_KEYLIST_MODE_LOCAL
GPGME_KEYLIST_MODE_LOCAL
symbol specifies that the local
keyring should be searched for keys in the keylisting operation. This
is the default.
GPGME_KEYLIST_MODE_EXTERN
GPGME_KEYLIST_MODE_EXTERN
symbol specifies that an external
source should be should be searched for keys in the keylisting
operation. The type of external source is dependant on the crypto
engine used. For example, it can be a remote keyserver or LDAP
certificate server.
At least one of GPGME_KEYLIST_MODE_LOCAL
and
GPGME_KEYLIST_MODE_EXTERN
must be specified. For future binary
compatibility, you should get the current mode with
gpgme_get_keylist_mode
and modify it by setting or clearing the
appropriate bits, and then using that calulcated value in the
gpgme_set_keylisting_mode
operation. This will leave all other
bits in the mode value intact (in particular those that are not used
in the current version of the library).
The function returns GPGME_No_Error
if the mode could be set
correctly, and GPGME_Invalid_Value
if ctx is not a valid
pointer or mode is not a valid mode.
gpgme_get_keylist_mode
returns the current key
listing mode of the context ctx. This value can then be
modified and used in a subsequent gpgme_set_keylist_mode
operation to only affect the desired bits (and leave all others
intact).
The function returns 0 if ctx is not a valid pointer, and the current mode otherwise. Note that 0 is not a valid mode value.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmePassphraseCb
type is the type of functions usable as
passphrase callback function.
The string desc contains a text usable to be displayed to the
user of the application. The function should return a passphrase for
the context when invoked with desc not being NULL
.
The user may store information about the resources associated with the returned passphrase in *r_hd. When the passphrase is no longer needed by GPGME, the passphrase callback function will be called with desc being NULL, and r_hd being the same as at the first invocation.
gpgme_set_passphrase_cb
sets the function that is
used when a passphrase needs to be provided by the user to
passfunc. The function passfunc needs to implemented by
the user, and whenever it is called, it is called with its first
argument being 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 gpgme_set_passphrase_cb
with passfunc being
NULL
.
gpgme_get_passphrase_cb
returns the function that
is used when a passphrase needs to be provided by the user in
*passfunc, and the first argument for this function in
*hook_value. If no passphrase callback is set, or ctx is
not a valid pointer, NULL
is returned in both variables.
passfunc or hook_value can be NULL
. In this case,
the corresponding value will not be returned.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 `doc/DETAILS' in the section PROGRESS.
gpgme_set_progress_cb
sets the function that is
used when progress information about a cryptographic operation is
available. The function progfunc needs to implemented by the
user, and whenever it is called, it is called with its first argument
being 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 gpgme_set_progress_cb
with progfunc being
NULL
.
gpgme_get_progress_cb
returns the function that is
used to inform the user about the progress made in *progfunc,
and the first argument for this function in *hook_value. If no
progress callback is set, or ctx is not a valid pointer,
NULL
is returned in both variables.
progfunc or hook_value can be NULL
. In this case,
the corresponding value will not be returned.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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.
6.4.1 Listing Keys Browsing the list of available keys. 6.4.2 Information About Keys Requesting detailed information about keys. 6.4.3 Manipulating Keys Operations on keys. 6.4.4 Generating Keys Creating new key pairs. 6.4.5 Exporting Keys Retrieving key data from the key ring. 6.4.6 Importing Keys Adding keys to the key ring. 6.4.7 Deleting Keys Removing keys from the key ring.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_keylist_start
initiates a key listing
operation inside the context ctx. It sets everything up so that
subsequent invocations of gpgme_op_keylist_next
return the keys
in the list.
If pattern is NULL
, all available keys are returned.
Otherwise, pattern contains an engine specific expression that
is used to limit the list to all keys matching the pattern.
If secret_only is not 0
, the list is restricted to secret
keys only.
The context will be busy until either all keys are received (and
gpgme_op_keylist_next
returns GPGME_EOF
), or
gpgme_op_keylist_end
is called to finish the operation.
The function returns GPGME_Invalid_Value
if ctx is not a
valid pointer, and passes through any errors that are reported by the
crypto engine support routines.
gpgme_op_keylist_ext_start
initiates an extended
key listing operation inside the context ctx. It sets
everything up so that subsequent invocations of
gpgme_op_keylist_next
return the keys in the list.
If pattern or *pattern is NULL
, all available keys
are returned. Otherwise, pattern is a NULL
terminated
array of strings that are used to limit the list to all keys matching
at least one of the patterns verbatim.
If secret_only is not 0
, the list is restricted to secret
keys only.
The value of reserved must be 0
.
The context will be busy until either all keys are received (and
gpgme_op_keylist_next
returns GPGME_EOF
), or
gpgme_op_keylist_end
is called to finish the operation.
The function returns GPGME_Invalid_Value
if ctx is not a
valid pointer, and passes through any errors that are reported by the
crypto engine support routines.
gpgme_op_keylist_next
returns the next key in the
list created by a previous gpgme_op_keylist_start
operation in
the context ctx. The key will have one reference for the user.
See section 6.4.3 Manipulating Keys.
This is the only way to get at GpgmeKey
objects in
GPGME.
If the last key in the list has already been returned,
gpgme_op_keylist_next
returns GPGME_EOF
.
The function returns GPGME_Invalid_Value
if ctx or
r_key is not a valid pointer, GPGME_No_Request
if there
is no pending operation, GPGME_Out_Of_Core
if there is not
enough memory for the operation.
gpgme_op_keylist_next
ends a pending key list
operation in the context ctx.
The function returns GPGME_Invalid_Value
if ctx is not a
valid pointer, GPGME_No_Request
if there is no pending
operation, GPGME_Out_Of_Core
if at some time during the
operation there was not enough memory available.
The following example illustrates how all keys containing a certain
string (g10code
) can be listed with their key ID and the name
and e-mail address of the main user ID:
GpgmeCtx ctx; GpgmeError err = gpgme_new (&ctx); if (!err) { err = gpgme_op_keylist_start (ctx, "g10code", 0); while (!err && (err = gpgme_op_keylist_next (ctx, &key)) != GPGME_EOF) { printf ("%s: %s <%s>\n", gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0), gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0), gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0)); gpgme_key_release (key); } gpgme_release (ctx); } if (err) { fprintf (stderr, "%s: can not list keys: %s\n", argv[0], gpgme_strerror (err)); exit (1); } |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_key_get_as_xml
returns a string in
XML format describing the key key. The user has to
release the string with free
.
The function returns NULL
if key is not a valid pointer,
or there is not enough memory available.
GpgmeAttr
type is used to specify a key or trust item
attribute. The following attributes are defined:
GPGME_ATTR_KEYID
For trust items, the trust item refers to the key with this ID.
GPGME_ATTR_FPR
GPGME_ATTR_ALGO
enum gcry_pk_algos
values in the gcrypt library.
GPGME_ATTR_LEN
GPGME_ATTR_CREATED
GPGME_ATTR_EXPIRE
GPGME_ATTR_OTRUST
GPGME_ATTR_USERID
For trust items, this is the user ID associated with this trust item.
GPGME_ATTR_NAME
GPGME_ATTR_EMAIL
GPGME_ATTR_COMMENT
GPGME_ATTR_VALIDITY
For trust items, this is the validity that is associated with this trust item.
GPGME_ATTR_UID_REVOKED
1
if the user ID is revoked, and 0
otherwise.
GPGME_ATTR_UID_INVALID
1
if the user ID is invalid, and 0
otherwise.
GPGME_ATTR_LEVEL
GPGME_ATTR_TYPE
GPGME_ATTR_IS_SECRET
1
, otherwise it is NULL
or 0
.
GPGME_ATTR_KEY_REVOKED
1
if the key is revoked, and 0
otherwise.
GPGME_ATTR_KEY_INVALID
1
if the key is invalid, and 0
otherwise.
GPGME_ATTR_KEY_EXPIRED
1
if the key is expired, and 0
otherwise.
GPGME_ATTR_KEY_DISABLED
1
if the key is disabled, and 0
otherwise.
GPGME_ATTR_KEY_CAPS
GPGME_ATTR_CAN_ENCRYPT
1
if the sub key can be used
for encryption, and 0
otherwise.
GPGME_ATTR_CAN_SIGN
1
if the sub key can be used
for signatures, and 0
otherwise.
GPGME_ATTR_CAN_CERTIFY
1
if the sub key can be used
for certifications, and 0
otherwise.
GPGME_ATTR_SERIAL
GPGME_ATTR_ISSUE
GPGME_ATTR_CHAINID
GpgmeValidity
type is used to specify the validity of a user ID
in a key. The following validities are defined:
GPGME_VALIDITY_UNKNOWN
GPGME_VALIDITY_UNDEFINED
GPGME_VALIDITY_NEVER
GPGME_VALIDITY_MARGINAL
GPGME_VALIDITY_FULL
GPGME_VALIDITY_ULTIMATE
gpgme_key_get_string_attr
returns the value of the
string-representable attribute what of key key. If the
attribute is an attribute of a sub key or an user ID, idx
specifies the sub key or user ID of which the attribute value is
returned. The argument reserved is reserved for later use and
should be NULL
.
The string returned is only valid as long as the key is valid.
The function returns 0
if an attribute can't be returned as a
string, key is not a valid pointer, idx out of range,
or reserved not NULL
.
gpgme_key_get_ulong_attr
returns the value of the
number-representable attribute what of key key. If the
attribute is an attribute of a sub key or an user ID, idx
specifies the sub key or user ID of which the attribute value is
returned. The argument reserved is reserved for later use and
should be NULL
.
The function returns 0
if the attribute can't be returned as a
number, key is not a valid pointer, idx out of range,
or reserved not NULL
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_key_ref
acquires an additional reference for
the key key.
gpgme_key_ref
releases a reference for the key
key. If this was the last reference, the key will be destroyed
and all resources associated to it will be released.
The function gpgme_key_release
is an alias for
gpgme_key_unref
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_genkey
generates a new key pair in the
context ctx and puts it into the standard key ring if both
pubkey and seckey are NULL
. In this case the
function returns immediately after starting the operation, and does
not wait for it to complete. If pubkey is not NULL
it
should be the handle for an empty (newly created) data object, and
upon successful completion the data object will contain the public
key. If seckey is not NULL
it should be the handle for
an empty (newly created) data object, and upon successful completion
the data object will contain the secret key.
Note that not all crypto engines support this interface equally.
GnuPG does not support pubkey and subkey, they should be
both NULL
, and the key pair will be added to the standard key
ring. GpgSM does only support pubkey, the secret key will be
stored by gpg-agent
. GpgSM expects pubkey being not
NULL
.
The argument parms specifies parameters for the key in an XML string. The details about the format of parms are specific to the crypto engine used by ctx. Here is an example for GnuPG as the crypto engine:
<GnupgKeyParms format="internal"> Key-Type: DSA Key-Length: 1024 Subkey-Type: ELG-E Subkey-Length: 1024 Name-Real: Joe Tester Name-Comment: with stupid passphrase Name-Email: joe@foo.bar Expire-Date: 0 Passphrase: abc </GnupgKeyParms> |
Here is an example for GpgSM as the crypto engine:
<GnupgKeyParms format="internal"> Key-Type: RSA Key-Length: 1024 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester Name-Email: joe@foo.bar </GnupgKeyParms> |
Strings should be given in UTF-8 encoding. The only format supported
for now is "internal". The content of the GnupgKeyParms
container is passed verbatim to GnuPG. Control statements are not
allowed.
The function returns GPGME_No_Error
if the operation could be
started successfully, GPGME_Invalid_Value
if parms is not
a valid XML string, GPGME_Not_Supported
if pubkey or
seckey is not valid, and GPGME_General_Error
if no key
was created by the backend.
gpgme_op_genkey_start
initiates a
gpgme_op_genkey
operation. It can be completed by calling
gpgme_wait
on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error
if the operation could be
started successfully, GPGME_Invalid_Value
if parms is not
a valid XML string, and GPGME_Not_Supported
if pubkey or
seckey is not NULL
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_export
extracts the public keys of the
user IDs in recipients and returns them in the data buffer
keydata. The type of the public keys returned is determined by
the ASCII armor attribute set for the context ctx.
The function returns GPGME_No_Error
if the operation completed
successfully, GPGME_Invalid_Value
if recipients is
NULL
or keydata is not a valid empty data buffer, and
passes through any errors that are reported by the crypto engine
support routines.
gpgme_op_export_start
initiates a
gpgme_op_export
operation. It can be completed by calling
gpgme_wait
on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error
if the operation could be
started successfully, and GPGME_Invalid_Value
if
recipients is NULL
or keydata is not a valid empty
data buffer.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_import
adds the keys in the data buffer
keydata to the key ring of the crypto engine used by ctx.
The format of keydata can be ASCII armored, for example,
but the details are specific to the crypto engine.
More information about the import is available with
gpgme_get_op_info
. See section 6.6.6 Detailed Results.
The function returns GPGME_No_Error
if the import was completed
successfully, GPGME_Invalid_Value
if keydata if ctx
or keydata is not a valid pointer, and GPGME_No_Data
if
keydata is an empty data buffer.
gpgme_op_import_start
initiates a
gpgme_op_import
operation. It can be completed by calling
gpgme_wait
on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error
if the import could be
started successfully, GPGME_Invalid_Value
if keydata if
ctx or keydata is not a valid pointer, and
GPGME_No_Data
if keydata is an empty data buffer.
gpgme_op_import_ext
is like
gpgme_op_import
, but also returns the number of processed keys
in nr. This is the same as the count
information in the
detailed results available with gpgme_get_op_info
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_delete
deletes the key key from the
key ring of the crypto engine used by ctx. If
allow_secret is 0
, only public keys are deleted,
otherwise secret keys are deleted as well, if that is supported.
The function returns GPGME_No_Error
if the key was deleted
successfully, GPGME_Invalid_Value
if ctx or key is
not a valid pointer, GPGME_Invalid_Key
if key could not
be found in the keyring, and GPGME_Conflict
if the secret key
for key is available, but allow_secret is zero.
gpgme_op_delete_start
initiates a
gpgme_op_delete
operation. It can be completed by calling
gpgme_wait
on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error
if the operation was
started successfully, and GPGME_Invalid_Value
if ctx or
key is not a valid pointer.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Caution: The trust items interface is experimental.
GpgmeTrustItem
type is a handle for a trust item.
6.5.1 Listing Trust Items Browsing the list of available trust items. 6.5.2 Information About Trust Items Requesting detailed information about trust items. 6.5.3 Manipulating Trust Items Operations on trust items.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_trustlist_start
initiates a trust item
listing operation inside the context ctx. It sets everything up
so that subsequent invocations of gpgme_op_trustlist_next
return
the trust items in the list.
The string 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 max_level is currently ignored.
The context will be busy until either all trust items are received
(and gpgme_op_trustlist_next
returns GPGME_EOF
), or
gpgme_op_trustlist_end
is called to finish the operation.
The function returns GPGME_Invalid_Value
if ctx is not a
valid pointer, and passes through any errors that are reported by the
crypto engine support routines.
gpgme_op_trustlist_next
returns the next trust
item in the list created by a previous gpgme_op_trustlist_start
operation in the context ctx. The trust item can be destroyed
with gpgme_trust_item_release
. See section 6.5.3 Manipulating Trust Items.
This is the only way to get at GpgmeTrustItem
objects in
GPGME.
If the last trust item in the list has already been returned,
gpgme_op_trustlist_next
returns GPGME_EOF
.
The function returns GPGME_Invalid_Value
if ctx or
r_item is not a valid pointer, GPGME_No_Request
if there
is no pending operation, GPGME_Out_Of_Core
if there is not
enough memory for the operation.
gpgme_op_trustlist_next
ends a pending key list
operation in the context ctx.
The function returns GPGME_Invalid_Value
if ctx is not a
valid pointer, GPGME_No_Request
if there is no pending
operation, GPGME_Out_Of_Core
if at some time during the
operation there was not enough memory available.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Trust items have attributes which can be queried using the interfaces below. The attribute identifiers are shared with those for key attributes. See section 6.4.2 Information About Keys.
gpgme_trust_item_get_string_attr
returns the value
of the string-representable attribute what of trust item
item. The arguments idx and reserved are reserved
for later use and should be 0
and NULL
respectively.
The string returned is only valid as long as the key is valid.
The function returns 0
if an attribute can't be returned as a
string, key is not a valid pointer, idx out of range,
or reserved not NULL
.
gpgme_trust_item_get_int_attr
returns the value of
the number-representable attribute what of trust item
item. If the attribute occurs more than once in the trust item,
the index is specified by idx. However, currently no such
attribute exists, so idx should be 0
. The argument
reserved is reserved for later use and should be NULL
.
The function returns 0
if the attribute can't be returned as a
number, key is not a valid pointer, idx out of range,
or reserved not NULL
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_trust_item_release
destroys a
GpgmeTrustItem
object and releases all associated resources.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
6.6.1 Decrypt Decrypting a ciphertext. 6.6.2 Verify Verifying a signature. 6.6.3 Decrypt and Verify Decrypting a signed ciphertext. 6.6.4 Sign Creating a signature. 6.6.5 Encrypt Encrypting a plaintext. 6.6.6 Detailed Results How to obtain more info about the operation.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_decrypt
decrypts the ciphertext in the
data object cipher and stores it into the data object
plain.
The function returns GPGME_No_Error
if the ciphertext could be
decrypted successfully, GPGME_Invalid_Value
if ctx,
cipher or plain is not a valid pointer,
GPGME_No_Data
if cipher does not contain any data to
decrypt, GPGME_Decryption_Failed
if cipher is not a valid
cipher text, 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.
gpgme_op_decrypt_start
initiates a
gpgme_op_decrypt
operation. It can be completed by calling
gpgme_wait
on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error
if the operation could be
started successfully, and GPGME_Invalid_Value
if cipher
or plain is not a valid pointer.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeSigStat
type holds the result of a signature check, or
the combined result of all signatures. The following results are
possible:
GPGME_SIG_STAT_NONE
GPGME_SIG_STAT_GOOD
GPGME_SIG_STAT_GOOD_EXP
GPGME_SIG_STAT_GOOD_EXPKEY
GPGME_SIG_STAT_BAD
GPGME_SIG_STAT_NOKEY
GPGME_SIG_STAT_NOSIG
GPGME_SIG_STAT_ERROR
GPGME_SIG_STAT_DIFF
gpgme_get_sig_status
.
gpgme_op_verify
verifies that the signature in the
data object sig is a valid signature. If plain is
initialized with plaintext data, it is assumed that sig is a
detached signature, and its validity for the plaintext given in
plain is verified. If plain is an uninitialized data
object, it is assumed that sig is a normal (or cleartext)
signature, and the plaintext is available in plain after
successful verification.
The combined status of all signatures is returned in r_stat.
The results of the individual signature verifications can be retrieved
with gpgme_get_sig_status
and gpgme_get_sig_key
.
The function returns GPGME_No_Error
if the operation could be
completed successfully, GPGME_Invalid_Value
if ctx,
sig, plain or r_stat is not a valid pointer,
GPGME_No_Data
if sig does not contain any data to verify,
and passes through any errors that are reported by the crypto engine
support routines.
gpgme_op_verify_start
initiates a
gpgme_op_verify
operation. It can be completed by calling
gpgme_wait
on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error
if the operation could be
started successfully, GPGME_Invalid_Value
if ctx,
sig, plain or r_stat is not a valid pointer, and
GPGME_No_Data
if sig or plain does not contain any
data to verify.
gpgme_get_sig_status
receives information about a
signature after the gpgme_op_verify
or
gpgme_op_verify_decrypt
operation. A single detached signature
can contain signatures by more than one key. The idx specifies
which signature's information should be retrieved, starting from
0.
The status of the signature will be returned in r_stat if it is
not NULL
. The creation time stamp of the signature will be
returned in r_created if it is not NULL.
The function returns a statically allocated string that contains the
fingerprint of the key which signed the plaintext, or NULL
if
ctx is not a valid pointer, the operation is still pending, or
no verification could be performed.
gpgme_get_sig_status
but may be used
to retrieve more detailed information. ctx should be the context
used for the last signature verification, idx is used to enumerate
over all signatures starting with 0
and whatidx should be
0
unless otherwise stated.
The following values may be used for what:
GPGME_ATTR_FPR
GPGME_ATTR_ERRTOK
0
returns an error token associated with validity calculation,
a value of 1
return an error token related to the certificate
checking.
gpgme_get_sig_string_attr
but used
for attributes which can be represented by an unsigned long
data
type. ctx should be the context used for the last signature
verification, idx is used to enumerate over all signatures
starting with 0
and whatidx should be 0
unless
otherwise stated.
The following values may be used for what:
GPGME_ATTR_CREATED
gpgme_get_sig_status
.
GPGME_ATTR_EXPIRE
GPGME_ATTR_VALIDITY
GPGME_VALIDITY_UNKNOWN
, GPGME_VALIDITY_NEVER
,
GPGME_VALIDITY_MARGINAL
or GPGME_VALIDITY_FULL
.
GPGME_ATTR_SIG_STATUS
gpgme_get_sig_status
.
GPGME_ATTR_SIG_SUMMARY
The defined bits are:
GPGME_SIGSUM_VALID
GPGME_SIGSUM_GREEN
GPGME_SIGSUM_RED
GPGME_SIGSUM_KEY_REVOKED
GPGME_SIGSUM_KEY_EXPIRED
GPGME_SIGSUM_SIG_EXPIRED
GPGME_SIGSUM_KEY_MISSING
GPGME_SIGSUM_CRL_MISSING
GPGME_SIGSUM_CRL_TOO_OLD
GPGME_SIGSUM_BAD_POLICY
GPGME_SIGSUM_SYS_ERROR
gpgme_get_sig_status
receives a GpgmeKey
object for the key which was used to verify the signature after the
gpgme_op_verify
or gpgme_op_verify_decrypt
operation. A
single detached signature can contain signatures by more than one key.
The idx specifies which signature's information should be
retrieved, starting from 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 gpgme_get_sig_status
.
The function returns GPGME_No_Error
if the key could be
returned, GPGME_Invalid_Value
if r_key is not a valid
pointer, GPGME_Invalid_Key
if the fingerprint is not valid,
GPGME_EOF
if idx is too large, or some other error value
if a problem occurred requesting the key.
gpgme_get_notation
can be used to retrieve
notation data from the last signature check in the context ctx.
If there is notation data available from the last signature check,
this function may be used to return this notation data as a string.
The string is an XML representation of that data embedded in a
<notation> container. The user has to release the string with
free
.
The function returns a string if the notation data is available or
NULL
if there is no such data available.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_decrypt_verify
decrypts the ciphertext in
the data object cipher and stores it into the data object
plain. If cipher contains signatures, they will be
verified and their combined status will be returned in r_stat.
After the operation completed, gpgme_op_get_sig_status
and
gpgme_op_get_sig_key
can be used to retrieve more information
about the signatures.
The function returns GPGME_No_Error
if the ciphertext could be
decrypted successfully, GPGME_Invalid_Value
if ctx,
cipher, plain or r_stat is not a valid pointer,
GPGME_No_Data
if cipher does not contain any data to
decrypt, GPGME_Decryption_Failed
if cipher is not a valid
cipher text, 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.
gpgme_op_decrypt_verify_start
initiates a
gpgme_op_decrypt_verify
operation. It can be completed by
calling gpgme_wait
on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error
if the operation could be
started successfully, GPGME_Invalid_Value
if ctx,
cipher, plain or r_stat is not a valid pointer, and
GPGME_No_Data
if cipher does not contain any data to
decrypt.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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).
6.6.4.1 Selecting Signers How to choose the keys to sign with. 6.6.4.2 Creating a Signature How to create a signature.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_signers_clear
releases a reference for each
key on the signers list and removes the list of signers from the
context ctx.
Every context starts with an empty list.
gpgme_signers_add
adds the key key to the
list of signers in the context ctx.
Calling this function acquires an additional reference for the key.
gpgme_signers_enum
returns the seqth key in
the list of signers in the context ctx. An additional reference
is acquired for the user.
If seq is out of range, NULL
is returned.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeSigMode
type is used to specify the desired type of a
signature. The following modes are available:
GPGME_SIG_MODE_NORMAL
GPGME_SIG_MODE_DETACH
GPGME_SIG_MODE_CLEAR
gpgme_op_sign
creates a signature for the text in
the data object plain and returns it in the data object
sig. The type of the signature created is determined by the
ASCII armor and text mode attributes set for the context
ctx and the requested signature mode mode.
More information about the signatures is available with
gpgme_get_op_info
. See section 6.6.6 Detailed Results.
If an S/MIME signed message is created using the CMS crypto engine,
the number of certificates to include in the message can be specified
with gpgme_set_include_certs
. See section 6.3.4 Included Certificates.
The function returns GPGME_No_Error
if the signature could be
created successfully, GPGME_Invalid_Value
if ctx,
plain or sig is not a valid pointer, GPGME_No_Data
if the signature could not be created, 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.
gpgme_op_sign_start
initiates a
gpgme_op_sign
operation. It can be completed by calling
gpgme_wait
on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error
if the operation could be
started successfully, and GPGME_Invalid_Value
if ctx,
plain or sig is not a valid pointer.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
6.6.5.1 Selecting Recipients How to choose the recipients. 6.6.5.2 Encrypting a Plaintext How to encrypt a plaintext.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeRecipients
type is a handle for a set of recipients
that can be used in an encryption process.
gpgme_recipients_new
creates a new, empty set of
recipients and returns a handle for it in r_rset.
The function returns GPGME_No_Error
if the recipient set could
be created successfully, and GPGME_Out_Of_Core
if not enough
memory was available.
gpgme_recipients_release
destroys the set of
recipients rset and releases all associated resources.
gpgme_recipients_add_name
adds the recipient
name to the set of recipients rset. This is equivalent to
gpgme_recipients_add_name_with_validity
with a validity of
GPGME_VALIDITY_UNKNOWN
.
The function returns GPGME_No_Error
if the recipient was added
successfully, GPGME_Invalid_Value
if rset or name
is not a valid pointer, and GPGME_Out_Of_Core
if not enough
memory is available.
gpgme_recipients_add_name_with_validity
adds the
recipient name with the validity val to the set of
recipients rset. If the validity is not known, the function
gpgme_recipients_add_name
can be used.
See section 6.4.2 Information About Keys, for the possible values for val.
The function returns GPGME_No_Error
if the recipient was added
successfully, GPGME_Invalid_Value
if rset or name
is not a valid pointer, and GPGME_Out_Of_Core
if not enough
memory is available.
gpgme_recipients_count
returns the number of
recipients in the set rset.
gpgme_recipients_enum_open
creates a new iterator
iter that can be used to walk through the set of recipients in
rset, using gpgme_recipients_enum_read
.
If the iterator is not needed anymore, it can be closed with
gpgme_recipients_enum_close
.
The function returns GPGME_No_Error
if the enumerator was
successfully created and GPGME_Invalid_Value
if rset or
iter is not a valid pointer.
gpgme_recipients_enum_read
returns a string
containing the name of the next recipient in the set rset for
the iterator iter. The string is valid as long as rset is
valid or the function is called the next time with the same recipient
set and iterator, whatever is earlier.
gpgme_recipients_enum_close
releases the iterator
iter for the recipient set rset.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_encrypt
encrypts the plaintext in the data
object plain for the recipients rset and stores the
ciphertext in the data object cipher. The type of the
ciphertext created is determined by the ASCII armor and text
mode attributes set for the context ctx.
If GPGME_Invalid_Recipients
is returned, some recipients in
rset are invalid, but not all. In this case the plaintext is
encrypted for all valid recipients and returned in cipher. More
information about the invalid recipients is available with
gpgme_get_op_info
. See section 6.6.6 Detailed Results.
If recp is NULL
, symmetric rather than public key
encryption is performed. Symmetrically encrypted cipher text can be
deciphered with gpgme_op_decrypt
. Note that in this case the
crypto backend needs to retrieve a passphrase from the user.
Symmetric encryption is currently only supported for the OpenPGP
crypto backend.
The function returns GPGME_No_Error
if the ciphertext could be
created successfully, GPGME_Invalid_Value
if ctx,
rset, plain or cipher is not a valid pointer,
GPGME_No_Recipients
if rset does not contain any valid
recipients, GPGME_Invalid_Recipients
if rset contains
some invalid recipients, 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.
gpgme_op_encrypt_start
initiates a
gpgme_op_encrypt
operation. It can be completed by calling
gpgme_wait
on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error
if the operation could be
started successfully, GPGME_Invalid_Value
if ctx,
rset, plain or cipher is not a valid pointer, and
GPGME_No_Recipients
if rset does not contain any valid
recipients.
gpgme_op_encrypt_sign
does a combined encrypt and
sign operation. It is used like gpgme_op_encrypt
, but the
ciphertext also contains signatures for the signers listed in
ctx.
The combined encrypt and sign operation is currently only available for the OpenPGP crypto engine.
gpgme_op_encrypt_sign_start
initiates a
gpgme_op_encrypt_sign
operation. It can be completed by
calling gpgme_wait
on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error
if the operation could be
started successfully, GPGME_Invalid_Value
if ctx,
rset, plain or cipher is not a valid pointer, and
GPGME_No_Recipients
if rset does not contain any valid
recipients.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_get_op_info
retrieves more information about
the last crypto operation.
The function returns a string in the XML format. The user has to
release the string with free
.
Here is a sample of the information that might be returned:
<GnupgOperationInfo> <signature> <detached/> <!-- or cleartext or standard --> <algo>17</algo> <hashalgo>2</hashalgo> <micalg>pgp-sha1</micalg> <sigclass>01</sigclass> <created>9222222</created> <fpr>121212121212121212</fpr> </signature> </GnupgOperationInfo> |
Currently, the only operations that return additional information are encrypt, sign and import. See section 6.6.5 Encrypt, See section 6.6.4 Sign, See section 6.4.6 Importing Keys.
The function returns a string or NULL
if no such data is
available.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GPGME supports running operations synchronously and asynchronously. You can use asynchronous operation to set up a context up to initiating the desired operation, but delay performing it to a later point.
Furthermore, you can use an external event loop to control exactly when GPGME runs. This ensures that GPGME only runs when necessary and also prevents it from blocking for a long time.
6.7.1 Waiting For Completion Waiting until an operation is completed. 6.7.2 Cancelling an Operation Interrupting a running operation. 6.7.3 Hooking Up Into Idle Time Doing something when nothing has to be done. 6.7.4 Using External Event Loops Advanced control over what happens when.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_wait
continues the pending operation within
the context ctx. In particular, it ensures the data exchange
between GPGME and the crypto backend and watches over the
run time status of the backend process.
If hang is true, the function does not return until the operation is completed or cancelled. Otherwise the function will not block for a long time.
The error status of the finished operation is returned in status
if gpgme_wait
does not return NULL
.
The ctx argument can be NULL
. In that case,
gpgme_wait
waits for any context to complete its operation.
gpgme_wait
can be used only in conjunction with any context
that has a pending operation initiated with one of the
gpgme_op_*_start
functions except gpgme_op_keylist_start
and gpgme_op_trustlist_start
(for which you should use the
corresponding gpgme_op_*_next
functions). If ctx is
NULL
, all of such contexts are waited upon and possibly
returned. Synchronous operations running in parallel, as well as key
and trust item list operations, do not affect gpgme_wait
.
In a multi-threaded environment, only one thread should ever call
gpgme_wait
at any time, irregardless if ctx is specified
or not. This means that all calls to this function should be fully
synchronized by locking primitives.
The function returns the ctx of the context which has finished the operation.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_cancel
tries to cancel the pending
operation. A running synchronous operation in the context or the
function gpgme_wait
with this context as its ctx argument
might notice the cancellation flag and return. It is currently not
guaranteed to work under all circumstances. Its current primary
purpose is to prevent asking for a passphrase again in the passphrase
callback.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeIdleFunc
type is the type of functions usable as
an idle function that can be registered with gpgme_register_idle
.
gpgme_register_idle
can be used to register
idle as the idle function.
idle will be called whenever GPGME thinks that it is
idle and time can better be spent elsewhere. Setting idle to
NULL
disables use of the idle function (this is the default).
The function returns the old idle function, or NULL
if none was
registered yet.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GPGME hides the complexity of the communication between the
library and the crypto engine. The price of this convenience is that
the calling thread can block arbitrary long waiting for the data
returned by the crypto engine. In single-threaded programs, in
particular if they are interactive, this is an unwanted side-effect.
OTOH, if gpgme_wait
is used without the hang option being
enabled, it might be called unnecessarily often, wasting CPU time that
could be used otherwise.
The I/O callback interface described in this section lets the user take control over what happens when. GPGME will provide the user with the file descriptors that should be monitored, and the callback functions that should be invoked when a file descriptor is ready for reading or writing. It is then the user's responsibility to decide when to check the file descriptors and when to invoke the 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, GPGME will never block. This gives the user mroe control over the program flow, and allows to perform other tasks when GPGME would block otherwise.
By using this advanced mechanism, GPGME can be integrated smoothly into GUI toolkits like GTK+ even for single-threaded programs.
6.7.4.1 I/O Callback Interface How I/O callbacks are registered. 6.7.4.2 Registering I/O Callbacks How to use I/O callbacks for a context. 6.7.4.3 I/O Callback Example An example how to use I/O callbacks. 6.7.4.4 I/O Callback Example GTK+ How to use GPGME with GTK+. 6.7.4.5 I/O Callback Example GDK How to use GPGME with GDK.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeIOCb
type is the type of functions which
GPGME wants to register as I/O callback handlers using the
GpgmeRegisterIOCb
functions provided by the user.
data and fd are provided by GPGME when the I/O callback handler is registered, and should be passed through to the handler when it is invoked by the user because it noticed activity on the file descriptor fd.
GpgmeRegisterIOCb
type is the type of functions which can
be called by GPGME to register an I/O callback funtion
fnc for the file descriptor fd with the user.
fnc_data should be passed as the first argument to fnc
when the handler is invoked (the second argument should be fd).
If dir is 0, fnc should be called by the user when
fd is ready for writing. If dir is 1, fnc should be
called when fd is ready for reading.
data was provided by the user when registering the
GpgmeRegisterIOCb
function with GPGME and will always
be passed as the first argument when registering a callback function.
For example, the user can use this to determine the event loop to
which the file descriptor should be added.
GPGME will call this function when a crypto operation is
initiated in a context for which the user has registered I/O callback
handler functions with gpgme_set_io_cbs
. It can also call this
function when it is in an I/O callback handler for a file descriptor
associated to this context.
The user should return a unique handle in tag identifying this
I/O callback registration, which will be passed to the
GpgmeRegisterIOCb
function without interpretation when the file
descriptor should not be monitored anymore.
GpgmeRemoveIOCb
type is the type of functions which can be
called by GPGME to remove an I/O callback handler that was
registered before. tag is the handle that was returned by the
GpgmeRegisterIOCb
for this I/O callback.
GPGME can call this function when a crypto operation is in an I/O callback. It will also call this function when the context is destroyed while an operation is pending.
GpgmeEventIO
type specifies the type of an event that is
reported to the user by GPGME as a consequence of an I/O
operation. The following events are defined:
GPGME_EVENT_DONE
GpgmeError
variable that contains the status of the operation
that finished. This event is signalled after the last I/O callback
has been removed.
GPGME_EVENT_NEXT_KEY
gpgme_op_keylist_start
operation, the next key was
received from the crypto engine. The accompanying type_data is
a GpgmeKey
variable that contains the key with one reference
for the user.
GPGME_EVENT_NEXT_TRUSTITEM
gpgme_op_trustlist_start
operation, the next trust item
was received from the crypto engine. The accompanying type_data
is a GpgmeTrustItem
variable that contains the trust item with
one reference for the user.
GpgmeEventIOCb
type is the type of functions which can be
called by GPGME to signal an event for an operation running
in a context which has I/O callback functions registered by the user.
data was provided by the user when registering the
GpgmeEventIOCb
function with GPGME and will always be
passed as the first argument when registering a callback function.
For example, the user can use this to determine the context in which
this event has occured.
type will specify the type of event that has occured.
type_data specifies the event further, as described in the above
list of possible GpgmeEventIO
types.
GPGME can call this function in an I/O callback handler.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeRegisterIOCb add
void *add_data
add
function when
it is called by GPGME. For example, it can be used to
determine the event loop to which the file descriptor should be added.
GpgmeRemoveIOCb remove
GpgmeEventIOCb event
void *event_data
event
function when
it is called by GPGME. For example, it can be used to
determine the context in which the event has occured.
gpgme_set_io_cbs
enables the I/O callback
interface for the context ctx. The I/O callback functions are
specified by io_cbs.
If io_cbs->add
is NULL
, the I/O callback interface
is disabled for the context, and normal operation is restored.
gpgme_get_io_cbs
returns the I/O callback
functions set with gpgme_set_io_cbs
in io_cbs.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To actually use an external event loop, you have to implement the I/O callback functions that are used by GPGME to register and unregister file descriptors. Furthermore, you have to actually monitor these file descriptors for activity and call the appropriate I/O callbacks.
The following example illustrates how to do that. The example uses locking to show in which way the the callbacks and the event loop can run concurrently. For the event loop, we use a fixed array. For a real-world implementation, you should use a dynamically sized structure because the number of file descriptors needed for a crypto operation in GPGME is not predictable.
#include <pthread.h> #include <sys/types.h> #include <gpgme.h> /* The following structure holds the result of a crypto operation. */ struct op_result { int done; GpgmeError err; }; /* The following structure holds the data associated with one I/O callback. */ struct one_fd { int fd; int dir; GpgmeIOCb fnc; void *fnc_data; }; struct event_loop { pthread_mutex_t lock; #define MAX_FDS 32 /* Unused slots are marked with FD being -1. */ struct one_fd fds[MAX_FDS]; }; |
The following functions implement the I/O callback interface.
GpgmeError add_io_cb (void *data, int fd, int dir, GpgmeIOCb fnc, void *fnc_data, void **r_tag) { struct event_loop *loop = data; struct one_fd *fds = loop->fds; int i; pthread_mutex_lock (&loop->lock); for (i = 0; i < MAX_FDS; i++) { if (fds[i].fd == -1) { fds[i].fd = fd; fds[i].dir = dir; fds[i].fnc = fnc; fds[i].fnc_data = fnc_data; break; } } pthread_mutex_unlock (&loop->lock); if (i == MAX_FDS) return GPGME_General_Error; *r_tag = &fds[i]; return 0; } void remove_io_cb (void *tag) { struct one_fd *fd = tag; pthread_mutex_lock (&loop->lock); fd->fd = -1; pthread_mutex_unlock (&loop->lock); } void event_io_cb (void *data, GpgmeEventIO type, void *type_data) { struct op_result *result = data; GpgmeError *err = data; /* We don't support list operations here. */ if (type == GPGME_EVENT_DONE) { result->done = 1; result->err = *data; } } |
The final missing piece is the event loop, which will be presented next. We only support waiting for the success of a single operation.
int do_select (struct event_loop *loop) { fd_set rfds; fd_set wfds; int i, n; int any = 0; pthread_mutex_lock (&loop->lock); FD_ZERO (&rfds); FD_ZERO (&wfds); for (i = 0; i < FDLIST_MAX; i++) if (fdlist[i].fd != -1) FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds); pthread_mutex_unlock (&loop->unlock); do { n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0); } while (n < 0 && errno == EINTR); if (n < 0) return n; /* Error or timeout. */ pthread_mutex_lock (&loop->lock); for (i = 0; i < FDLIST_MAX && n; i++) { if (fdlist[i].fd != -1) { if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds)) { assert (n); n--; any = 1; /* The I/O callback handler can register/remove callbacks, so we have to unlock the file descriptor list. */ pthread_mutex_unlock (&loop->lock); (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd); pthread_mutex_lock (&loop->lock); } } } pthread_mutex_unlock (&loop->lock); return any; } void wait_for_op (struct event_loop *loop, struct op_result *result) { int ret; do { ret = do_select (loop); } while (ret >= 0 && !result->done); return ret; } |
The main function shows how to put it all together.
int main (int argc, char *argv[]) { struct event_loop loop; struct op_result result; GpgmeCtx ctx; GpgmeError err; GpgmeData sig, text; GpgmeSigStat status; int i; struct GpgmeIOCbs io_cbs = { add_io_cb, &loop, remove_io_cb, event_io_cb, &result }; /* Initialize the loop structure. */ loop.lock = PTHREAD_MUTEX_INITIALIZER; for (i = 0; i < MAX_FDS; i++) loop->fds[i].fd = -1; /* Initialize the result structure. */ result.done = 0; err = gpgme_data_new_from_file (&sig, "signature", 1); if (!err) err = gpgme_data_new_from_file (&text, "text", 1); if (!err) err = gpgme_new (&ctx); if (!err) { gpgme_set_io_cbs (ctx, &io_cbs); err = gpgme_op_verify_start (ctx, sig, text, &status); } if (err) { fprintf (stderr, "gpgme error: %s\n", gpgme_strerror (err)); exit (1); } wait_for_op (&loop, &result); if (!result.done) { fprintf (stderr, "select error\n"); exit (1); } if (!result.err) { fprintf (stderr, "verification failed: %s\n", gpgme_strerror (result.err)); exit (1); } /* Evaluate STATUS. */ ... return 0; } |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The I/O callback interface can be used to integrate GPGME with the GTK+ event loop. The following code snippets shows how this can be done using the appropriate register and remove I/O callback functions. In this example, the private data of the register I/O callback function is unused. The event notifications is missing because it does not require any GTK+ specific setup.
#include <gtk/gtk.h> struct my_gpgme_io_cb { GpgmeIOCb fnc; void *fnc_data; guint input_handler_id }; void my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) { struct my_gpgme_io_cb *iocb = data; (*(iocb->fnc)) (iocb->data, source); } void my_gpgme_remove_io_cb (void *data) { struct my_gpgme_io_cb *iocb = data; gtk_input_remove (data->input_handler_id); } void my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc, void *fnc_data, void **tag) { struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); iocb->fnc = fnc; iocb->data = fnc_data; iocb->input_handler_id = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE, my_gpgme_io_callback, 0, iocb, NULL); *tag = iocb; return 0; } |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The I/O callback interface can also be used to integrate GPGME with the GDK event loop. The following code snippets shows how this can be done using the appropriate register and remove I/O callback functions. In this example, the private data of the register I/O callback function is unused. The event notifications is missing because it does not require any GDK specific setup.
It is very similar to the GTK+ example in the previous section.
#include <gdk/gdk.h> struct my_gpgme_io_cb { GpgmeIOCb fnc; void *fnc_data; gint tag; }; void my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) { struct my_gpgme_io_cb *iocb = data; (*(iocb->fnc)) (iocb->data, source); } void my_gpgme_remove_io_cb (void *data) { struct my_gpgme_io_cb *iocb = data; gdk_input_remove (data->tag); } void my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc, void *fnc_data, void **tag) { struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); iocb->fnc = fnc; iocb->data = fnc_data; iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE, my_gpgme_io_callback, iocb, NULL); *tag = iocb; return 0; } |
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |