[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

## C.10 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.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.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.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.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.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.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 signatureThis 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.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 sessionGet 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.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 structureThis 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 parametersThis 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)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 bitsThis 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 bitsThis 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.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 coefficientThis 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 parametersThis 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.Sets some default priority on the ciphers, key exchange methods, macs and compression methods. This function also includes weak algorithms.

**Thisisthesameascalling:**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.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.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

`userdata`

parameter is passed to the`sign_func`

verbatim, 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 keyThis 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 keyThis 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.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 signatureThis 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 signatureThis 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 signatureThis 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)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_size`

is 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 signatureThis 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.**Deprecatedin:**2.12.0

[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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