Next: TLS Inner Application (TLS/IA) functions, Previous: GnuTLS-extra functions, Up: Function reference
The following functions are to be used for OpenPGP certificate handling. Their prototypes lie in gnutls/openpgp.h.
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 files should contain non encrypted keys.
The special keyword "auto" is also accepted as
subkey_id
. In that case thegnutls_openpgp_crt_get_auth_subkey()
will be used to retrieve the subkey.Returns: On success,
GNUTLS_E_SUCCESS
is returned, otherwise a negative error value.Since: 2.4.0
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 files should only contain one key which is not encrypted.
Returns: On success,
GNUTLS_E_SUCCESS
is returned, otherwise a negative error value.
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 files should only contain one key which is not encrypted.
The special keyword "auto" is also accepted as
subkey_id
. In that case thegnutls_openpgp_crt_get_auth_subkey()
will be used to retrieve the subkey.Returns: On success,
GNUTLS_E_SUCCESS
is returned, otherwise a negative error value.Since: 2.4.0
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 files should contain non encrypted keys.
Returns: On success,
GNUTLS_E_SUCCESS
is returned, otherwise a negative error value.
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,
GNUTLS_E_SUCCESS
is returned, otherwise a negative error value.
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,
GNUTLS_E_SUCCESS
is returned, otherwise a negative error value.
res: is a
gnutls_certificate_credentials_t
structure.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).
With this function the subkeys of the certificate are not used.
Returns: On success,
GNUTLS_E_SUCCESS
(zero) is returned, otherwise an error code is returned.
key: should contain a
gnutls_openpgp_crt_t
structurehostname: 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:
GNUTLS_E_SUCCESS
on success, or an error code.
key: The structure to be initialized
This function will deinitialize a key structure.
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
GNUTLS_E_SHORT_MEMORY_BUFFER
will be returned.Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
crt: the structure that contains the OpenPGP public key.
keyid: the struct to save the keyid.
flag: Non zero 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 zero 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 zero and no authentication subkey exists, then a valid subkey will be returned even if it is not marked for authentication.
Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
key: the structure that contains the OpenPGP public key.
Get key creation time.
Returns: the timestamp when the OpenPGP key was created.
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.
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.
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
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:
GNUTLS_KEY_DIGITAL_SIGNATURE
,GNUTLS_KEY_KEY_ENCIPHERMENT
.Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
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
NULL
to only get thesizeof_buf
.sizeof_buf: holds the maximum size of
buf
, on return hold the actual/required size ofbuf
.Extracts the userID from the parsed OpenPGP key.
Returns:
GNUTLS_E_SUCCESS
on success, and if the index of the ID does not existGNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
, or an error code.
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
gnutls_pk_algorithm_t
enumeration on success, or a negative value on error.
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
gnutls_malloc()
and will be stored in the appropriate datum.Returns:
GNUTLS_E_SUCCESS
on success, otherwise an error.Since: 2.4.0
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
gnutls_malloc()
and will be stored in the appropriate datum.Returns:
GNUTLS_E_SUCCESS
on success, otherwise an error.Since: 2.4.0
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
GNUTLS_E_INVALID_REQUEST
.Returns: the 64-bit preferred keyID of the OpenPGP 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
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 value on error.
Since: 2.4.0
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
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
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
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
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.
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
gnutls_pk_algorithm_t
enumeration on success, or a negative value on error.Since: 2.4.0
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
gnutls_malloc()
and will be stored in the appropriate datum.Returns:
GNUTLS_E_SUCCESS
on success, otherwise an error.Since: 2.4.0
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
gnutls_malloc()
and will be stored in the appropriate datum.Returns:
GNUTLS_E_SUCCESS
on success, otherwise an error.Since: 2.4.0
key: the structure that contains the OpenPGP public key.
idx: is the subkey index
Get subkey revocation status. A negative value indicates an error.
Returns: true (1) if the key has been revoked, or false (0) if it has not.
Since: 2.4.0
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
GNUTLS_KEY_DIGITAL_SIGNATURE
orGNUTLS_KEY_KEY_ENCIPHERMENT
.A negative value may be returned in case of parsing error.
Returns: key usage value.
Since: 2.4.0
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 value on errors.
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
gnutls_openpgp_crt_t
format. The output will be stored in 'key'.Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
key: The structure to be initialized
This function will initialize an OpenPGP key structure.
Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
cert: The structure to be printed
format: Indicate the format to use
out: Newly allocated datum with zero terminated string.
This function will pretty print an OpenPGP certificate, suitable for display to a human.
The format should be zero for future compatibility.
The output
out
needs to be deallocate usinggnutls_free()
.Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
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,
GNUTLS_E_SUCCESS
(zero) is returned, otherwise an error code is returned.
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
verify
and will be one or more of thegnutls_certificate_status_t
enumerated elements bitwise or'd.Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
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
verify
and will be one or more of the gnutls_certificate_status_t enumerated elements bitwise or'd.Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
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:
GNUTLS_E_SUCCESS
on success (if keyid exists) and a negative error code on failure.
keyring: The structure to be initialized
This function will deinitialize a keyring structure.
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 value on error.
ring: Holds the keyring.
idx: the index of the certificate to export
cert: An uninitialized
gnutls_openpgp_crt_t
structureThis function will extract an OpenPGP certificate from the given keyring. If the index given is out of range
GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
will be returned. The returned structure needs to be deinited.Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
keyring: The structure to store the parsed key.
data: The RAW or BASE64 encoded keyring.
format: One of
gnutls_openpgp_keyring_fmt
elements.This function will convert the given RAW or Base64 encoded keyring to the native
gnutls_openpgp_keyring_t
format. The output will be stored in 'keyring'.Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
keyring: The structure to be initialized
This function will initialize an keyring structure.
Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
key: The structure to be initialized
This function will deinitialize a key structure.
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
gnutls_malloc()
and will be stored in the appropriate datum.Returns:
GNUTLS_E_SUCCESS
on success, otherwise an error.Since: 2.4.0
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
gnutls_malloc()
and will be stored in the appropriate datum.Returns:
GNUTLS_E_SUCCESS
on success, otherwise an error.Since: 2.4.0
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
gnutls_malloc()
and will be stored in the appropriate datum.Returns:
GNUTLS_E_SUCCESS
on success, otherwise an error.Since: 2.4.0
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
gnutls_malloc()
and will be stored in the appropriate datum.Returns:
GNUTLS_E_SUCCESS
on success, otherwise an error.Since: 2.4.0
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: zero 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:
GNUTLS_E_SUCCESS
on success, or an error code.Since: 2.4.0
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
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
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
gnutls_pk_algorithm_t
enumeration on success, or a negative value on error.Since: 2.4.0
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_E_INVALID_REQUEST
.
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 value indicates an error.
Since: 2.4.0
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 value on error.
Since: 2.4.0
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
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
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
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
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
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
gnutls_pk_algorithm_t
enumeration on success, or a negative value on error.Since: 2.4.0
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 value indicates an error.
Since: 2.4.0
key: The structure to store the parsed key.
data: The RAW or BASE64 encoded key.
format: One of
gnutls_openpgp_crt_fmt_t
elements.password: not used for now
flags: should be zero
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:
GNUTLS_E_SUCCESS
on success, or an error code.
key: The structure to be initialized
This function will initialize an OpenPGP key structure.
Returns:
GNUTLS_E_SUCCESS
on success, or an error code.
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.
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
gnutls_openpgp_privkey_set_preferred_key_id()
before calling this function to set the subkey to use.Returns: On success,
GNUTLS_E_SUCCESS
is returned, otherwise a negative error value.
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.