info gnutls

C.9 Compatibility API

The following functions are carried over from old GnuTLS released. They might be removed at a later version. Their prototypes lie in ‘gnutls/compat.h’.

gnutls_certificate_set_rsa_export_params

Function: void gnutls_certificate_set_rsa_export_params (gnutls_certificate_credentials_t res, gnutls_rsa_params_t rsa_params)

res: is a gnutls_certificate_credentials_t structure

rsa_params: is a structure that holds temporary RSA parameters.

Description: This function will set the temporary RSA parameters for a certificate server to use. These parameters will be used in RSA-EXPORT cipher suites.

gnutls_certificate_type_set_priority

Function: int gnutls_certificate_type_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_certificate_type_t elements.

Description: Sets the priority on the certificate types supported by gnutls. Priority is higher for elements specified before others. After specifying the types you want, you must append a 0. Note that the certificate type priority is set on the client. The server does not use the cert type priority except for disabling types that were not specified.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_cipher_set_priority

Function: int gnutls_cipher_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_cipher_algorithm_t elements.

Description: Sets the priority on the ciphers supported by gnutls. Priority is higher for elements specified before others. After specifying the ciphers you want, you must append a 0. Note that the priority is set on the client. The server does not use the algorithm’s priority except for disabling algorithms that were not specified.

Returns: GNUTLS_E_SUCCESS (0) on success, or a negative error code.

gnutls_compression_set_priority

Function: int gnutls_compression_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_compression_method_t elements.

Description: Sets the priority on the compression algorithms supported by gnutls. Priority is higher for elements specified before others. After specifying the algorithms you want, you must append a 0. Note that the priority is set on the client. The server does not use the algorithm’s priority except for disabling algorithms that were not specified.

TLS 1.0 does not define any compression algorithms except NULL. Other compression algorithms are to be considered as gnutls extensions.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_kx_set_priority

Function: int gnutls_kx_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_kx_algorithm_t elements.

Description: Sets the priority on the key exchange algorithms supported by gnutls. Priority is higher for elements specified before others. After specifying the algorithms you want, you must append a 0. Note that the priority is set on the client. The server does not use the algorithm’s priority except for disabling algorithms that were not specified.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_mac_set_priority

Function: int gnutls_mac_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_mac_algorithm_t elements.

Description: Sets the priority on the mac algorithms supported by gnutls. Priority is higher for elements specified before others. After specifying the algorithms you want, you must append a 0. Note that the priority is set on the client. The server does not use the algorithm’s priority except for disabling algorithms that were not specified.

Returns: GNUTLS_E_SUCCESS on success, 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

Description: 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 (0) is returned, otherwise a negative error value.

Deprecated: Use gnutls_privkey_sign_hash() instead.

gnutls_protocol_set_priority

Function: int gnutls_protocol_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_protocol_t elements.

Description: Sets the priority on the protocol versions supported by gnutls. This function actually enables or disables protocols. Newer protocol versions always have highest priority.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_rsa_export_get_modulus_bits

Function: int gnutls_rsa_export_get_modulus_bits (gnutls_session_t session)

session: is a gnutls session

Description: Get the export RSA parameter’s modulus size.

Returns: The bits used in the last RSA-EXPORT key exchange with the peer, or a negative error code in case of error.

gnutls_rsa_export_get_pubkey

Function: int gnutls_rsa_export_get_pubkey (gnutls_session_t session, gnutls_datum_t * exponent, gnutls_datum_t * modulus)

session: is a gnutls session

exponent: will hold the exponent.

modulus: will hold the modulus.

Description: This function will return the peer’s public key exponent and modulus used in the last RSA-EXPORT authentication. The output parameters must be freed with gnutls_free().

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise an error code is returned.

gnutls_rsa_params_cpy

Function: int gnutls_rsa_params_cpy (gnutls_rsa_params_t dst, gnutls_rsa_params_t src)

dst: Is the destination structure, which should be initialized.

src: Is the source structure

Description: This function will copy the RSA parameters structure from source to destination.

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_rsa_params_deinit

Function: void gnutls_rsa_params_deinit (gnutls_rsa_params_t rsa_params)

rsa_params: Is a structure that holds the parameters

Description: This function will deinitialize the RSA parameters structure.

gnutls_rsa_params_export_pkcs1

Function: int gnutls_rsa_params_export_pkcs1 (gnutls_rsa_params_t params, gnutls_x509_crt_fmt_t format, unsigned char * params_data, size_t * params_data_size)

params: Holds the RSA parameters

format: the format of output params. One of PEM or DER.

params_data: will contain a PKCS1 RSAPublicKey structure PEM or DER encoded

params_data_size: holds the size of params_data (and will be replaced by the actual size of parameters)

Description: This function will export the given RSA parameters to a PKCS1 RSAPublicKey structure. If the buffer provided is not long enough to hold the output, then GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.

If the structure is PEM encoded, it will have a header of "BEGIN RSA PRIVATE KEY".

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_rsa_params_export_raw

Function: int gnutls_rsa_params_export_raw (gnutls_rsa_params_t rsa, gnutls_datum_t * m, gnutls_datum_t * e, gnutls_datum_t * d, gnutls_datum_t * p, gnutls_datum_t * q, gnutls_datum_t * u, unsigned int * bits)

rsa: a structure that holds the rsa parameters

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

bits: if non null will hold the prime’s number of bits

Description: This function will export the RSA 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, or an negative error code.

gnutls_rsa_params_generate2

Function: int gnutls_rsa_params_generate2 (gnutls_rsa_params_t params, unsigned int bits)

params: The structure where the parameters will be stored

bits: is the prime’s number of bits

Description: This function will generate new temporary RSA parameters for use in RSA-EXPORT ciphersuites. This function is normally slow.

Note that if the parameters are to be used in export cipher suites the bits value should be 512 or less. Also note that the generation of new RSA parameters is only useful to servers. Clients use the parameters sent by the server, thus it’s no use calling this in client side.

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_rsa_params_import_pkcs1

Function: int gnutls_rsa_params_import_pkcs1 (gnutls_rsa_params_t params, const gnutls_datum_t * pkcs1_params, gnutls_x509_crt_fmt_t format)

params: A structure where the parameters will be copied to

pkcs1_params: should contain a PKCS1 RSAPublicKey structure PEM or DER encoded

format: the format of params. PEM or DER.

Description: This function will extract the RSAPublicKey found in a PKCS1 formatted structure.

If the structure is PEM encoded, it should have a header of "BEGIN RSA PRIVATE KEY".

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_rsa_params_import_raw

Function: int gnutls_rsa_params_import_raw (gnutls_rsa_params_t rsa_params, const gnutls_datum_t * m, const gnutls_datum_t * e, const gnutls_datum_t * d, const gnutls_datum_t * p, const gnutls_datum_t * q, const gnutls_datum_t * u)

rsa_params: Is a structure will hold the parameters

m: holds the modulus

e: holds the public exponent

d: holds the private exponent

p: holds the first prime (p)

q: holds the second prime (q)

u: holds the coefficient

Description: This function will replace the parameters in the given structure. The new parameters should be stored in the appropriate gnutls_datum.

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_rsa_params_init

Function: int gnutls_rsa_params_init (gnutls_rsa_params_t * rsa_params)

rsa_params: Is a structure that will hold the parameters

Description: This function will initialize the temporary RSA parameters structure.

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_set_default_export_priority

Function: int gnutls_set_default_export_priority (gnutls_session_t session)

session: is a gnutls_session_t structure.

Description: Sets some default priority on the ciphers, key exchange methods, macs and compression methods. This function also includes weak algorithms.

This is the same as calling: gnutls_priority_set_direct (session, "EXPORT", NULL);

This function is kept around for backwards compatibility, but because of its wide use it is still fully supported. If you wish to allow users to provide a string that specify which ciphers to use (which is recommended), you should use gnutls_priority_set_direct() or gnutls_priority_set() instead.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_sign_callback_get

Function: gnutls_sign_func gnutls_sign_callback_get (gnutls_session_t session, void ** userdata)

session: is a gnutls session

userdata: if non-NULL, will be set to abstract callback pointer.

Description: Retrieve the callback function, and its userdata pointer.

Returns: The function pointer set by gnutls_sign_callback_set(), or if not set, NULL.

Deprecated: Use the PKCS 11 interfaces instead.

gnutls_sign_callback_set

Function: void gnutls_sign_callback_set (gnutls_session_t session, gnutls_sign_func sign_func, void * userdata)

session: is a gnutls session

sign_func: function pointer to application’s sign callback.

userdata: void pointer that will be passed to sign callback.

Description: Set the callback function. The function must have this prototype:

typedef int (*gnutls_sign_func) (gnutls_session_t session, void *userdata, gnutls_certificate_type_t cert_type, const gnutls_datum_t * cert, const gnutls_datum_t * hash, gnutls_datum_t * signature);

The userdataparameter is passed to the sign_funcverbatim, and can be used to store application-specific data needed in the callback function. See also gnutls_sign_callback_get().

Deprecated: Use the PKCS 11 or gnutls_privkey_t interfacess like gnutls_privkey_import_ext() instead.

gnutls_x509_crl_sign

Function: int gnutls_x509_crl_sign (gnutls_x509_crl_t crl, gnutls_x509_crt_t issuer, gnutls_x509_privkey_t issuer_key)

crl: should contain a gnutls_x509_crl_t structure

issuer: is the certificate of the certificate issuer

issuer_key: holds the issuer’s private key

Description: This function is the same a gnutls_x509_crl_sign2() with no flags, and SHA1 as the hash algorithm.

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

Deprecated: Use gnutls_x509_crl_privkey_sign().

gnutls_x509_crq_sign

Function: int gnutls_x509_crq_sign (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key)

crq: should contain a gnutls_x509_crq_t structure

key: holds a private key

Description: This function is the same a gnutls_x509_crq_sign2() with no flags, and SHA1 as the hash algorithm.

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

Deprecated: Use gnutls_x509_crq_privkey_sign() instead.

gnutls_x509_crt_get_preferred_hash_algorithm

Function: int gnutls_x509_crt_get_preferred_hash_algorithm (gnutls_x509_crt_t crt, gnutls_digest_algorithm_t * hash, unsigned int * mand)

crt: Holds the certificate

hash: The result of the call with the hash algorithm used for signature

mand: If non (0) it means that the algorithm MUST use this hash. May be NULL.

Description: This function will read the certifcate and return the appropriate digest algorithm to use for signing with this certificate. Some certificates (i.e. DSA might not be able to sign without the preferred algorithm).

Deprecated: Please use gnutls_pubkey_get_preferred_hash_algorithm().

Returns: the 0 if the hash algorithm is found. A negative error code is returned on error.

Since: 2.12.0

gnutls_x509_crt_get_verify_algorithm

Function: int gnutls_x509_crt_get_verify_algorithm (gnutls_x509_crt_t crt, const gnutls_datum_t * signature, gnutls_digest_algorithm_t * hash)

crt: Holds the certificate

signature: contains the signature

hash: The result of the call with the hash algorithm used for signature

Description: This function will read the certifcate and the signed data to determine the hash algorithm used to generate the signature.

Deprecated: Use gnutls_pubkey_get_verify_algorithm() instead.

Returns: the 0 if the hash algorithm is found. A negative error code is returned on error.

Since: 2.8.0

gnutls_x509_crt_verify_data

Function: int gnutls_x509_crt_verify_data (gnutls_x509_crt_t crt, unsigned int flags, const gnutls_datum_t * data, const gnutls_datum_t * signature)

crt: Holds the certificate

flags: should be 0 for now

data: holds the data to be signed

signature: contains the signature

Description: This function will verify the given signed data, using the parameters from the certificate.

Deprecated. Please use gnutls_pubkey_verify_data().

Returns: In case of a verification failure GNUTLS_E_PK_SIG_VERIFY_FAILED is returned, and a positive code on success.

gnutls_x509_crt_verify_hash

Function: int gnutls_x509_crt_verify_hash (gnutls_x509_crt_t crt, unsigned int flags, const gnutls_datum_t * hash, const gnutls_datum_t * signature)

crt: Holds the certificate

flags: should be 0 for now

hash: holds the hash digest to be verified

signature: contains the signature

Description: This function will verify the given signed digest, using the parameters from the certificate.

Deprecated. Please use gnutls_pubkey_verify_data().

Returns: In case of a verification failure GNUTLS_E_PK_SIG_VERIFY_FAILED is returned, and a positive code on success.

gnutls_x509_privkey_sign_data

Function: int gnutls_x509_privkey_sign_data (gnutls_x509_privkey_t key, gnutls_digest_algorithm_t digest, unsigned int flags, const gnutls_datum_t * data, void * signature, size_t * signature_size)

key: Holds the key

digest: should be MD5 or SHA1

flags: should be 0 for now

data: holds the data to be signed

signature: will contain the signature

signature_size: holds the size of signature (and will be replaced by the new size)

Description: This function will sign the given data using a signature algorithm supported by the private key. Signature algorithms are always used together with a hash functions. Different hash functions may be used for the RSA algorithm, but only SHA-1 for the DSA keys.

If the buffer provided is not long enough to hold the output, then * signature_sizeis updated and GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.

Use gnutls_x509_crt_get_preferred_hash_algorithm() to determine the hash algorithm.

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

Deprecated: Use gnutls_privkey_sign_data().

gnutls_x509_privkey_sign_hash

Function: int gnutls_x509_privkey_sign_hash (gnutls_x509_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

Description: This function will sign the given hash using the private key. Do not use this function directly unless you know what it is. Typical signing requires the data to be hashed and stored in special formats (e.g. BER Digest-Info for RSA).

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

Deprecated in: 2.12.0

This document was generated on January 4, 2012 using texi2html 5.0.