C.3 OpenPGP Functions

The following functions are to be used for OpenPGP certificate handling. Their prototypes lie in ‘gnutls/openpgp.h’.

gnutls_certificate_set_openpgp_key_file2

Function: int gnutls_certificate_set_openpgp_key_file2 (gnutls_certificate_credentials_t res, const char * certfile, const char * keyfile, const char * subkey_id, gnutls_openpgp_crt_fmt_t format)

res: the destination context to save the data.

certfile: the file that contains the public key.

keyfile: the file that contains the secret key.

subkey_id: a hex encoded subkey id

format: the format of the keys

This funtion is used to load OpenPGP keys into the GnuTLS credential structure. The file should contain at least one valid non encrypted subkey.

The special keyword "auto" is also accepted as . In that case the will be used to retrieve the subkey.

Returns: On success, (0) is returned, otherwise a negative error value.

Since: 2.4.0

gnutls_certificate_set_openpgp_key_file

Function: int gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t res, const char * certfile, const char * keyfile, gnutls_openpgp_crt_fmt_t format)

res: the destination context to save the data.

certfile: the file that contains the public key.

keyfile: the file that contains the secret key.

format: the format of the keys

This funtion is used to load OpenPGP keys into the GnuTLS credentials structure. The file should contain at least one valid non encrypted subkey.

Returns: On success, (0) is returned, otherwise a negative error value.

gnutls_certificate_set_openpgp_key_mem2

Function: int gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t res, const gnutls_datum_t * cert, const gnutls_datum_t * key, const char * subkey_id, gnutls_openpgp_crt_fmt_t format)

res: the destination context to save the data.

cert: the datum that contains the public key.

key: the datum that contains the secret key.

subkey_id: a hex encoded subkey id

format: the format of the keys

This funtion is used to load OpenPGP keys into the GnuTLS credentials structure. The datum should contain at least one valid non encrypted subkey.

The special keyword "auto" is also accepted as . In that case the will be used to retrieve the subkey.

Returns: On success, (0) is returned, otherwise a negative error value.

Since: 2.4.0

gnutls_certificate_set_openpgp_key_mem

Function: int gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t res, const gnutls_datum_t * cert, const gnutls_datum_t * key, gnutls_openpgp_crt_fmt_t format)

res: the destination context to save the data.

cert: the datum that contains the public key.

key: the datum that contains the secret key.

format: the format of the keys

This funtion is used to load OpenPGP keys into the GnuTLS credential structure. The datum should contain at least one valid non encrypted subkey.

Returns: On success, (0) is returned, otherwise a negative error value.

gnutls_certificate_set_openpgp_keyring_file

Function: int gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t c, const char * file, gnutls_openpgp_crt_fmt_t format)

c: A certificate credentials structure

file: filename of the keyring.

format: format of keyring.

The function is used to set keyrings that will be used internally by various OpenPGP functions. For example to find a key when it is needed for an operations. The keyring will also be used at the verification functions.

Returns: On success, (0) is returned, otherwise a negative error value.

gnutls_certificate_set_openpgp_keyring_mem

Function: int gnutls_certificate_set_openpgp_keyring_mem (gnutls_certificate_credentials_t c, const opaque * data, size_t dlen, gnutls_openpgp_crt_fmt_t format)

c: A certificate credentials structure

data: buffer with keyring data.

dlen: length of data buffer.

format: the format of the keyring

The function is used to set keyrings that will be used internally by various OpenPGP functions. For example to find a key when it is needed for an operations. The keyring will also be used at the verification functions.

Returns: On success, (0) is returned, otherwise a negative error value.

gnutls_certificate_set_openpgp_key

Function: int gnutls_certificate_set_openpgp_key (gnutls_certificate_credentials_t res, gnutls_openpgp_crt_t crt, gnutls_openpgp_privkey_t pkey)

res: is a structure.

crt: contains an openpgp public key

pkey: is an openpgp private key

This function sets a certificate/private key pair in the gnutls_certificate_credentials_t structure. This function may be called more than once (in case multiple keys/certificates exist for the server).

Note that this function requires that the preferred key ids have been set and be used. See . Otherwise the master key will be used.

Returns: On success, (0) is returned, otherwise a negative error code is returned.

gnutls_openpgp_crt_check_hostname

Function: int gnutls_openpgp_crt_check_hostname (gnutls_openpgp_crt_t key, const char * hostname)

key: should contain a structure

hostname: A null terminated string that contains a DNS name

This function will check if the given key’s owner matches the given hostname. This is a basic implementation of the matching described in RFC2818 (HTTPS), which takes into account wildcards.

Returns: on success, or an error code.

gnutls_openpgp_crt_deinit

Function: void gnutls_openpgp_crt_deinit (gnutls_openpgp_crt_t key)

key: The structure to be initialized

This function will deinitialize a key structure.

gnutls_openpgp_crt_export

Function: int gnutls_openpgp_crt_export (gnutls_openpgp_crt_t key, gnutls_openpgp_crt_fmt_t format, void * output_data, size_t * output_data_size)

key: Holds the key.

format: One of gnutls_openpgp_crt_fmt_t elements.

output_data: will contain the key base64 encoded or raw

output_data_size: holds the size of output_data (and will be replaced by the actual size of parameters)

This function will convert the given key to RAW or Base64 format. If the buffer provided is not long enough to hold the output, then will be returned.

Returns: on success, or an error code.

gnutls_openpgp_crt_get_auth_subkey

Function: int gnutls_openpgp_crt_get_auth_subkey (gnutls_openpgp_crt_t crt, gnutls_openpgp_keyid_t keyid, unsigned int flag)

crt: the structure that contains the OpenPGP public key.

keyid: the struct to save the keyid.

flag: Non (0) indicates that a valid subkey is always returned.

Returns the 64-bit keyID of the first valid OpenPGP subkey marked for authentication. If flag is non (0) and no authentication subkey exists, then a valid subkey will be returned even if it is not marked for authentication. Returns the 64-bit keyID of the first valid OpenPGP subkey marked for authentication. If flag is non (0) and no authentication subkey exists, then a valid subkey will be returned even if it is not marked for authentication.

Returns: on success, or an error code.

gnutls_openpgp_crt_get_creation_time

Function: time_t gnutls_openpgp_crt_get_creation_time (gnutls_openpgp_crt_t key)

key: the structure that contains the OpenPGP public key.

Get key creation time.

Returns: the timestamp when the OpenPGP key was created.

gnutls_openpgp_crt_get_expiration_time

Function: time_t gnutls_openpgp_crt_get_expiration_time (gnutls_openpgp_crt_t key)

key: the structure that contains the OpenPGP public key.

Get key expiration time. A value of ’0’ means that the key doesn’t expire at all.

Returns: the time when the OpenPGP key expires.

gnutls_openpgp_crt_get_fingerprint

Function: int gnutls_openpgp_crt_get_fingerprint (gnutls_openpgp_crt_t key, void * fpr, size_t * fprlen)

key: the raw data that contains the OpenPGP public key.

fpr: the buffer to save the fingerprint, must hold at least 20 bytes.

fprlen: the integer to save the length of the fingerprint.

Get key fingerprint. Depending on the algorithm, the fingerprint can be 16 or 20 bytes.

Returns: On success, 0 is returned. Otherwise, an error code.

gnutls_openpgp_crt_get_key_id

Function: int gnutls_openpgp_crt_get_key_id (gnutls_openpgp_crt_t key, gnutls_openpgp_keyid_t keyid)

key: the structure that contains the OpenPGP public key.

keyid: the buffer to save the keyid.

Get key id string.

Returns: the 64-bit keyID of the OpenPGP key.

Since: 2.4.0

gnutls_openpgp_crt_get_key_usage

Function: int gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t key, unsigned int * key_usage)

key: should contain a gnutls_openpgp_crt_t structure

key_usage: where the key usage bits will be stored

This function will return certificate’s key usage, by checking the key algorithm. The key usage value will ORed values of the: , .

Returns: on success, or an error code.

gnutls_openpgp_crt_get_name

Function: int gnutls_openpgp_crt_get_name (gnutls_openpgp_crt_t key, int idx, char * buf, size_t * sizeof_buf)

key: the structure that contains the OpenPGP public key.

idx: the index of the ID to extract

buf: a pointer to a structure to hold the name, may be to only get the .

sizeof_buf: holds the maximum size of , on return hold the actual/required size of .

Extracts the userID from the parsed OpenPGP key.

Returns: on success, and if the index of the ID does not exist , or an error code.

gnutls_openpgp_crt_get_pk_algorithm

Function: gnutls_pk_algorithm_t gnutls_openpgp_crt_get_pk_algorithm (gnutls_openpgp_crt_t key, unsigned int * bits)

key: is an OpenPGP key

bits: if bits is non null it will hold the size of the parameters’ in bits

This function will return the public key algorithm of an OpenPGP certificate.

If bits is non null, it should have enough size to hold the parameters size in bits. For RSA the bits returned is the modulus. For DSA the bits returned are of the public exponent.

Returns: a member of the enumeration on success, or GNUTLS_PK_UNKNOWN on error.

gnutls_openpgp_crt_get_pk_dsa_raw

Function: int gnutls_openpgp_crt_get_pk_dsa_raw (gnutls_openpgp_crt_t crt, gnutls_datum_t * p, gnutls_datum_t * q, gnutls_datum_t * g, gnutls_datum_t * y)

crt: Holds the certificate

p: will hold the p

q: will hold the q

g: will hold the g

y: will hold the y

This function will export the DSA public key’s parameters found in the given certificate. The new parameters will be allocated using and will be stored in the appropriate datum.

Returns: on success, otherwise a negative error code.

Since: 2.4.0

gnutls_openpgp_crt_get_pk_rsa_raw

Function: int gnutls_openpgp_crt_get_pk_rsa_raw (gnutls_openpgp_crt_t crt, gnutls_datum_t * m, gnutls_datum_t * e)

crt: Holds the certificate

m: will hold the modulus

e: will hold the public exponent

This function will export the RSA public key’s parameters found in the given structure. The new parameters will be allocated using and will be stored in the appropriate datum.

Returns: on success, otherwise a negative error code.

Since: 2.4.0

gnutls_openpgp_crt_get_preferred_key_id

Function: int gnutls_openpgp_crt_get_preferred_key_id (gnutls_openpgp_crt_t key, gnutls_openpgp_keyid_t keyid)

key: the structure that contains the OpenPGP public key.

keyid: the struct to save the keyid.

Get preferred key id. If it hasn’t been set it returns .

Returns: the 64-bit preferred keyID of the OpenPGP key.

gnutls_openpgp_crt_get_revoked_status

Function: int gnutls_openpgp_crt_get_revoked_status (gnutls_openpgp_crt_t key)

key: the structure that contains the OpenPGP public key.

Get revocation status of key.

Returns: true (1) if the key has been revoked, or false (0) if it has not.

Since: 2.4.0

gnutls_openpgp_crt_get_subkey_count

Function: int gnutls_openpgp_crt_get_subkey_count (gnutls_openpgp_crt_t key)

key: is an OpenPGP key

This function will return the number of subkeys present in the given OpenPGP certificate.

Returns: the number of subkeys, or a negative error code on error.

Since: 2.4.0

gnutls_openpgp_crt_get_subkey_creation_time

Function: time_t gnutls_openpgp_crt_get_subkey_creation_time (gnutls_openpgp_crt_t key, unsigned int idx)

key: the structure that contains the OpenPGP public key.

idx: the subkey index

Get subkey creation time.

Returns: the timestamp when the OpenPGP sub-key was created.

Since: 2.4.0

gnutls_openpgp_crt_get_subkey_expiration_time

Function: time_t gnutls_openpgp_crt_get_subkey_expiration_time (gnutls_openpgp_crt_t key, unsigned int idx)

key: the structure that contains the OpenPGP public key.

idx: the subkey index

Get subkey expiration time. A value of ’0’ means that the key doesn’t expire at all.

Returns: the time when the OpenPGP key expires.

Since: 2.4.0

gnutls_openpgp_crt_get_subkey_fingerprint

Function: int gnutls_openpgp_crt_get_subkey_fingerprint (gnutls_openpgp_crt_t key, unsigned int idx, void * fpr, size_t * fprlen)

key: the raw data that contains the OpenPGP public key.

idx: the subkey index

fpr: the buffer to save the fingerprint, must hold at least 20 bytes.

fprlen: the integer to save the length of the fingerprint.

Get key fingerprint of a subkey. Depending on the algorithm, the fingerprint can be 16 or 20 bytes.

Returns: On success, 0 is returned. Otherwise, an error code.

Since: 2.4.0

gnutls_openpgp_crt_get_subkey_idx

Function: int gnutls_openpgp_crt_get_subkey_idx (gnutls_openpgp_crt_t key, const gnutls_openpgp_keyid_t keyid)

key: the structure that contains the OpenPGP public key.

keyid: the keyid.

Get subkey’s index.

Returns: the index of the subkey or a negative error value.

Since: 2.4.0

gnutls_openpgp_crt_get_subkey_id

Function: int gnutls_openpgp_crt_get_subkey_id (gnutls_openpgp_crt_t key, unsigned int idx, gnutls_openpgp_keyid_t keyid)

key: the structure that contains the OpenPGP public key.

idx: the subkey index

keyid: the buffer to save the keyid.

Get the subkey’s key-id.

Returns: the 64-bit keyID of the OpenPGP key.

gnutls_openpgp_crt_get_subkey_pk_algorithm

Function: gnutls_pk_algorithm_t gnutls_openpgp_crt_get_subkey_pk_algorithm (gnutls_openpgp_crt_t key, unsigned int idx, unsigned int * bits)

key: is an OpenPGP key

idx: is the subkey index

bits: if bits is non null it will hold the size of the parameters’ in bits

This function will return the public key algorithm of a subkey of an OpenPGP certificate.

If bits is non null, it should have enough size to hold the parameters size in bits. For RSA the bits returned is the modulus. For DSA the bits returned are of the public exponent.

Returns: a member of the enumeration on success, or GNUTLS_PK_UNKNOWN on error.

Since: 2.4.0

gnutls_openpgp_crt_get_subkey_pk_dsa_raw

Function: int gnutls_openpgp_crt_get_subkey_pk_dsa_raw (gnutls_openpgp_crt_t crt, unsigned int idx, gnutls_datum_t * p, gnutls_datum_t * q, gnutls_datum_t * g, gnutls_datum_t * y)

crt: Holds the certificate

idx: Is the subkey index

p: will hold the p

q: will hold the q

g: will hold the g

y: will hold the y

This function will export the DSA public key’s parameters found in the given certificate. The new parameters will be allocated using and will be stored in the appropriate datum.

Returns: on success, otherwise a negative error code.

Since: 2.4.0

gnutls_openpgp_crt_get_subkey_pk_rsa_raw

Function: int gnutls_openpgp_crt_get_subkey_pk_rsa_raw (gnutls_openpgp_crt_t crt, unsigned int idx, gnutls_datum_t * m, gnutls_datum_t * e)

crt: Holds the certificate

idx: Is the subkey index

m: will hold the modulus

e: will hold the public exponent

This function will export the RSA public key’s parameters found in the given structure. The new parameters will be allocated using and will be stored in the appropriate datum.

Returns: on success, otherwise a negative error code.

Since: 2.4.0

gnutls_openpgp_crt_get_subkey_revoked_status

Function: int gnutls_openpgp_crt_get_subkey_revoked_status (gnutls_openpgp_crt_t key, unsigned int idx)

key: the structure that contains the OpenPGP public key.

idx: is the subkey index

Get subkey revocation status. A negative error code indicates an error.

Returns: true (1) if the key has been revoked, or false (0) if it has not.

Since: 2.4.0

gnutls_openpgp_crt_get_subkey_usage

Function: int gnutls_openpgp_crt_get_subkey_usage (gnutls_openpgp_crt_t key, unsigned int idx, unsigned int * key_usage)

key: should contain a gnutls_openpgp_crt_t structure

idx: the subkey index

key_usage: where the key usage bits will be stored

This function will return certificate’s key usage, by checking the key algorithm. The key usage value will ORed values of or .

A negative error code may be returned in case of parsing error.

Returns: key usage value.

Since: 2.4.0

gnutls_openpgp_crt_get_version

Function: int gnutls_openpgp_crt_get_version (gnutls_openpgp_crt_t key)

key: the structure that contains the OpenPGP public key.

Extract the version of the OpenPGP key.

Returns: the version number is returned, or a negative error code on errors.

gnutls_openpgp_crt_import

Function: int gnutls_openpgp_crt_import (gnutls_openpgp_crt_t key, const gnutls_datum_t * data, gnutls_openpgp_crt_fmt_t format)

key: The structure to store the parsed key.

data: The RAW or BASE64 encoded key.

format: One of gnutls_openpgp_crt_fmt_t elements.

This function will convert the given RAW or Base64 encoded key to the native format. The output will be stored in ’key’.

Returns: on success, or an error code.

gnutls_openpgp_crt_init

Function: int gnutls_openpgp_crt_init (gnutls_openpgp_crt_t * key)

key: The structure to be initialized

This function will initialize an OpenPGP key structure.

Returns: on success, or an error code.

gnutls_openpgp_crt_print

Function: int gnutls_openpgp_crt_print (gnutls_openpgp_crt_t cert, gnutls_certificate_print_formats_t format, gnutls_datum_t * out)

cert: The structure to be printed

format: Indicate the format to use

out: Newly allocated datum with (0) terminated string.

This function will pretty print an OpenPGP certificate, suitable for display to a human.

The format should be (0) for future compatibility.

The output needs to be deallocate using .

Returns: on success, or an error code.

gnutls_openpgp_crt_set_preferred_key_id

Function: int gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t key, const gnutls_openpgp_keyid_t keyid)

key: the structure that contains the OpenPGP public key.

keyid: the selected keyid

This allows setting a preferred key id for the given certificate. This key will be used by functions that involve key handling.

Returns: On success, (0) is returned, otherwise a negative error code is returned.

gnutls_openpgp_crt_verify_ring

Function: int gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t key, gnutls_openpgp_keyring_t keyring, unsigned int flags, unsigned int * verify)

key: the structure that holds the key.

keyring: holds the keyring to check against

flags: unused (should be 0)

verify: will hold the certificate verification output.

Verify all signatures in the key, using the given set of keys (keyring).

The key verification output will be put in and will be one or more of the enumerated elements bitwise or’d.

Returns: on success, or an error code.

gnutls_openpgp_crt_verify_self

Function: int gnutls_openpgp_crt_verify_self (gnutls_openpgp_crt_t key, unsigned int flags, unsigned int * verify)

key: the structure that holds the key.

flags: unused (should be 0)

verify: will hold the key verification output.

Verifies the self signature in the key. The key verification output will be put in and will be one or more of the gnutls_certificate_status_t enumerated elements bitwise or’d.

Returns: on success, or an error code.

gnutls_openpgp_keyring_check_id

Function: int gnutls_openpgp_keyring_check_id (gnutls_openpgp_keyring_t ring, const gnutls_openpgp_keyid_t keyid, unsigned int flags)

ring: holds the keyring to check against

keyid: will hold the keyid to check for.

flags: unused (should be 0)

Check if a given key ID exists in the keyring.

Returns: on success (if keyid exists) and a negative error code on failure.

gnutls_openpgp_keyring_deinit

Function: void gnutls_openpgp_keyring_deinit (gnutls_openpgp_keyring_t keyring)

keyring: The structure to be initialized

This function will deinitialize a keyring structure.

gnutls_openpgp_keyring_get_crt_count

Function: int gnutls_openpgp_keyring_get_crt_count (gnutls_openpgp_keyring_t ring)

ring: is an OpenPGP key ring

This function will return the number of OpenPGP certificates present in the given keyring.

Returns: the number of subkeys, or a negative error code on error.

gnutls_openpgp_keyring_get_crt

Function: int gnutls_openpgp_keyring_get_crt (gnutls_openpgp_keyring_t ring, unsigned int idx, gnutls_openpgp_crt_t * cert)

ring: Holds the keyring.

idx: the index of the certificate to export

cert: An uninitialized structure

This function will extract an OpenPGP certificate from the given keyring. If the index given is out of range will be returned. The returned structure needs to be deinited.

Returns: on success, or an error code.

gnutls_openpgp_keyring_import

Function: int gnutls_openpgp_keyring_import (gnutls_openpgp_keyring_t keyring, const gnutls_datum_t * data, gnutls_openpgp_crt_fmt_t format)

keyring: The structure to store the parsed key.

data: The RAW or BASE64 encoded keyring.

format: One of elements.

This function will convert the given RAW or Base64 encoded keyring to the native format. The output will be stored in ’keyring’.

Returns: on success, or an error code.

gnutls_openpgp_keyring_init

Function: int gnutls_openpgp_keyring_init (gnutls_openpgp_keyring_t * keyring)

keyring: The structure to be initialized

This function will initialize an keyring structure.

Returns: on success, or an error code.

gnutls_openpgp_privkey_deinit

Function: void gnutls_openpgp_privkey_deinit (gnutls_openpgp_privkey_t key)

key: The structure to be initialized

This function will deinitialize a key structure.

gnutls_openpgp_privkey_export_dsa_raw

Function: int gnutls_openpgp_privkey_export_dsa_raw (gnutls_openpgp_privkey_t pkey, gnutls_datum_t * p, gnutls_datum_t * q, gnutls_datum_t * g, gnutls_datum_t * y, gnutls_datum_t * x)

pkey: Holds the certificate

p: will hold the p

q: will hold the q

g: will hold the g

y: will hold the y

x: will hold the x

This function will export the DSA private key’s parameters found in the given certificate. The new parameters will be allocated using and will be stored in the appropriate datum.

Returns: on success, otherwise a negative error code.

Since: 2.4.0

gnutls_openpgp_privkey_export_rsa_raw

Function: int gnutls_openpgp_privkey_export_rsa_raw (gnutls_openpgp_privkey_t pkey, gnutls_datum_t * m, gnutls_datum_t * e, gnutls_datum_t * d, gnutls_datum_t * p, gnutls_datum_t * q, gnutls_datum_t * u)

pkey: Holds the certificate

m: will hold the modulus

e: will hold the public exponent

d: will hold the private exponent

p: will hold the first prime (p)

q: will hold the second prime (q)

u: will hold the coefficient

This function will export the RSA private key’s parameters found in the given structure. The new parameters will be allocated using and will be stored in the appropriate datum.

Returns: on success, otherwise a negative error code.

Since: 2.4.0

gnutls_openpgp_privkey_export_subkey_dsa_raw

Function: int gnutls_openpgp_privkey_export_subkey_dsa_raw (gnutls_openpgp_privkey_t pkey, unsigned int idx, gnutls_datum_t * p, gnutls_datum_t * q, gnutls_datum_t * g, gnutls_datum_t * y, gnutls_datum_t * x)

pkey: Holds the certificate

idx: Is the subkey index

p: will hold the p

q: will hold the q

g: will hold the g

y: will hold the y

x: will hold the x

This function will export the DSA private key’s parameters found in the given certificate. The new parameters will be allocated using and will be stored in the appropriate datum.

Returns: on success, otherwise a negative error code.

Since: 2.4.0

gnutls_openpgp_privkey_export_subkey_rsa_raw

Function: int gnutls_openpgp_privkey_export_subkey_rsa_raw (gnutls_openpgp_privkey_t pkey, unsigned int idx, gnutls_datum_t * m, gnutls_datum_t * e, gnutls_datum_t * d, gnutls_datum_t * p, gnutls_datum_t * q, gnutls_datum_t * u)

pkey: Holds the certificate

idx: Is the subkey index

m: will hold the modulus

e: will hold the public exponent

d: will hold the private exponent

p: will hold the first prime (p)

q: will hold the second prime (q)

u: will hold the coefficient

This function will export the RSA private key’s parameters found in the given structure. The new parameters will be allocated using and will be stored in the appropriate datum.

Returns: on success, otherwise a negative error code.

Since: 2.4.0

gnutls_openpgp_privkey_export

Function: int gnutls_openpgp_privkey_export (gnutls_openpgp_privkey_t key, gnutls_openpgp_crt_fmt_t format, const char * password, unsigned int flags, void * output_data, size_t * output_data_size)

key: Holds the key.

format: One of gnutls_openpgp_crt_fmt_t elements.

password: the password that will be used to encrypt the key. (unused for now)

flags: (0) for future compatibility

output_data: will contain the key base64 encoded or raw

output_data_size: holds the size of output_data (and will be replaced by the actual size of parameters)

This function will convert the given key to RAW or Base64 format. If the buffer provided is not long enough to hold the output, then GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.

Returns: on success, or an error code.

Since: 2.4.0

gnutls_openpgp_privkey_get_fingerprint

Function: int gnutls_openpgp_privkey_get_fingerprint (gnutls_openpgp_privkey_t key, void * fpr, size_t * fprlen)

key: the raw data that contains the OpenPGP secret key.

fpr: the buffer to save the fingerprint, must hold at least 20 bytes.

fprlen: the integer to save the length of the fingerprint.

Get the fingerprint of the OpenPGP key. Depends on the algorithm, the fingerprint can be 16 or 20 bytes.

Returns: On success, 0 is returned, or an error code.

Since: 2.4.0

gnutls_openpgp_privkey_get_key_id

Function: int gnutls_openpgp_privkey_get_key_id (gnutls_openpgp_privkey_t key, gnutls_openpgp_keyid_t keyid)

key: the structure that contains the OpenPGP secret key.

keyid: the buffer to save the keyid.

Get key-id.

Returns: the 64-bit keyID of the OpenPGP key.

Since: 2.4.0

gnutls_openpgp_privkey_get_pk_algorithm

Function: gnutls_pk_algorithm_t gnutls_openpgp_privkey_get_pk_algorithm (gnutls_openpgp_privkey_t key, unsigned int * bits)

key: is an OpenPGP key

bits: if bits is non null it will hold the size of the parameters’ in bits

This function will return the public key algorithm of an OpenPGP certificate.

If bits is non null, it should have enough size to hold the parameters size in bits. For RSA the bits returned is the modulus. For DSA the bits returned are of the public exponent.

Returns: a member of the enumeration on success, or a negative error code on error.

Since: 2.4.0

gnutls_openpgp_privkey_get_preferred_key_id

Function: int gnutls_openpgp_privkey_get_preferred_key_id (gnutls_openpgp_privkey_t key, gnutls_openpgp_keyid_t keyid)

key: the structure that contains the OpenPGP public key.

keyid: the struct to save the keyid.

Get the preferred key-id for the key.

Returns: the 64-bit preferred keyID of the OpenPGP key, or if it hasn’t been set it returns .

gnutls_openpgp_privkey_get_revoked_status

Function: int gnutls_openpgp_privkey_get_revoked_status (gnutls_openpgp_privkey_t key)

key: the structure that contains the OpenPGP private key.

Get revocation status of key.

Returns: true (1) if the key has been revoked, or false (0) if it has not, or a negative error code indicates an error.

Since: 2.4.0

gnutls_openpgp_privkey_get_subkey_count

Function: int gnutls_openpgp_privkey_get_subkey_count (gnutls_openpgp_privkey_t key)

key: is an OpenPGP key

This function will return the number of subkeys present in the given OpenPGP certificate.

Returns: the number of subkeys, or a negative error code on error.

Since: 2.4.0

gnutls_openpgp_privkey_get_subkey_creation_time

Function: time_t gnutls_openpgp_privkey_get_subkey_creation_time (gnutls_openpgp_privkey_t key, unsigned int idx)

key: the structure that contains the OpenPGP private key.

idx: the subkey index

Get subkey creation time.

Returns: the timestamp when the OpenPGP key was created.

Since: 2.4.0

gnutls_openpgp_privkey_get_subkey_expiration_time

Function: time_t gnutls_openpgp_privkey_get_subkey_expiration_time (gnutls_openpgp_privkey_t key, unsigned int idx)

key: the structure that contains the OpenPGP private key.

idx: the subkey index

Get subkey expiration time. A value of ’0’ means that the key doesn’t expire at all.

Returns: the time when the OpenPGP key expires.

Since: 2.4.0

gnutls_openpgp_privkey_get_subkey_fingerprint

Function: int gnutls_openpgp_privkey_get_subkey_fingerprint (gnutls_openpgp_privkey_t key, unsigned int idx, void * fpr, size_t * fprlen)

key: the raw data that contains the OpenPGP secret key.

idx: the subkey index

fpr: the buffer to save the fingerprint, must hold at least 20 bytes.

fprlen: the integer to save the length of the fingerprint.

Get the fingerprint of an OpenPGP subkey. Depends on the algorithm, the fingerprint can be 16 or 20 bytes.

Returns: On success, 0 is returned, or an error code.

Since: 2.4.0

gnutls_openpgp_privkey_get_subkey_idx

Function: int gnutls_openpgp_privkey_get_subkey_idx (gnutls_openpgp_privkey_t key, const gnutls_openpgp_keyid_t keyid)

key: the structure that contains the OpenPGP private key.

keyid: the keyid.

Get index of subkey.

Returns: the index of the subkey or a negative error value.

Since: 2.4.0

gnutls_openpgp_privkey_get_subkey_id

Function: int gnutls_openpgp_privkey_get_subkey_id (gnutls_openpgp_privkey_t key, unsigned int idx, gnutls_openpgp_keyid_t keyid)

key: the structure that contains the OpenPGP secret key.

idx: the subkey index

keyid: the buffer to save the keyid.

Get the key-id for the subkey.

Returns: the 64-bit keyID of the OpenPGP key.

Since: 2.4.0

gnutls_openpgp_privkey_get_subkey_pk_algorithm

Function: gnutls_pk_algorithm_t gnutls_openpgp_privkey_get_subkey_pk_algorithm (gnutls_openpgp_privkey_t key, unsigned int idx, unsigned int * bits)

key: is an OpenPGP key

idx: is the subkey index

bits: if bits is non null it will hold the size of the parameters’ in bits

This function will return the public key algorithm of a subkey of an OpenPGP certificate.

If bits is non null, it should have enough size to hold the parameters size in bits. For RSA the bits returned is the modulus. For DSA the bits returned are of the public exponent.

Returns: a member of the enumeration on success, or a negative error code on error.

Since: 2.4.0

gnutls_openpgp_privkey_get_subkey_revoked_status

Function: int gnutls_openpgp_privkey_get_subkey_revoked_status (gnutls_openpgp_privkey_t key, unsigned int idx)

key: the structure that contains the OpenPGP private key.

idx: is the subkey index

Get revocation status of key.

Returns: true (1) if the key has been revoked, or false (0) if it has not, or a negative error code indicates an error.

Since: 2.4.0

gnutls_openpgp_privkey_import

Function: int gnutls_openpgp_privkey_import (gnutls_openpgp_privkey_t key, const gnutls_datum_t * data, gnutls_openpgp_crt_fmt_t format, const char * password, unsigned int flags)

key: The structure to store the parsed key.

data: The RAW or BASE64 encoded key.

format: One of elements.

password: not used for now

flags: should be (0)

This function will convert the given RAW or Base64 encoded key to the native gnutls_openpgp_privkey_t format. The output will be stored in ’key’.

Returns: on success, or an error code.

gnutls_openpgp_privkey_init

Function: int gnutls_openpgp_privkey_init (gnutls_openpgp_privkey_t * key)

key: The structure to be initialized

This function will initialize an OpenPGP key structure.

Returns: on success, or an error code.

gnutls_openpgp_privkey_sec_param

Function: gnutls_sec_param_t gnutls_openpgp_privkey_sec_param (gnutls_openpgp_privkey_t key)

key: a key structure

This function will return the security parameter appropriate with this private key.

Returns: On success, a valid security parameter is returned otherwise is returned.

Since: 2.12.0

gnutls_openpgp_privkey_set_preferred_key_id

Function: int gnutls_openpgp_privkey_set_preferred_key_id (gnutls_openpgp_privkey_t key, const gnutls_openpgp_keyid_t keyid)

key: the structure that contains the OpenPGP public key.

keyid: the selected keyid

This allows setting a preferred key id for the given certificate. This key will be used by functions that involve key handling.

Returns: On success, 0 is returned, or an error code.

gnutls_openpgp_privkey_sign_hash

Function: int gnutls_openpgp_privkey_sign_hash (gnutls_openpgp_privkey_t key, const gnutls_datum_t * hash, gnutls_datum_t * signature)

key: Holds the key

hash: holds the data to be signed

signature: will contain newly allocated signature

This function will sign the given hash using the private key. You should use before calling this function to set the subkey to use.

Returns: On success, (0) is returned, otherwise a negative error value.

Deprecated: Use instead.

gnutls_openpgp_set_recv_key_function

Function: void gnutls_openpgp_set_recv_key_function (gnutls_session_t session, gnutls_openpgp_recv_key_func func)

session: a TLS session

func: the callback

This funtion will set a key retrieval function for OpenPGP keys. This callback is only useful in server side, and will be used if the peer sent a key fingerprint instead of a full key.

This document was generated by nmav on November 22, 2011 using texi2html 1.82.