extra

extra

Functions

Types and Values

Description

Functions

gnutls_ia_avp_func ()

int
(*gnutls_ia_avp_func) (gnutls_session_t session,
                       void *ptr,
                       const char *last,
                       size_t lastlen,
                       char **next,
                       size_t *nextlen);


gnutls_ia_free_client_credentials ()

void
gnutls_ia_free_client_credentials (gnutls_ia_client_credentials_t sc);

gnutls_ia_free_client_credentials is deprecated and should not be used in newly-written code.

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.

Parameters

sc

is a gnutls_ia_client_credentials_t structure.

 

gnutls_ia_allocate_client_credentials ()

int
gnutls_ia_allocate_client_credentials (gnutls_ia_client_credentials_t *sc);

gnutls_ia_allocate_client_credentials is deprecated and should not be used in newly-written code.

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate it.

Adding this credential to a session will enable TLS/IA, and will require an Application Phase after the TLS handshake (if the server support TLS/IA). Use gnutls_ia_enable() to toggle the TLS/IA mode.

Parameters

sc

is a pointer to a gnutls_ia_server_credentials_t structure.

 

Returns

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


gnutls_ia_free_server_credentials ()

void
gnutls_ia_free_server_credentials (gnutls_ia_server_credentials_t sc);

gnutls_ia_free_server_credentials is deprecated and should not be used in newly-written code.

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.

Parameters

sc

is a gnutls_ia_server_credentials_t structure.

 

gnutls_ia_allocate_server_credentials ()

int
gnutls_ia_allocate_server_credentials (gnutls_ia_server_credentials_t *sc);

gnutls_ia_allocate_server_credentials is deprecated and should not be used in newly-written code.

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate it.

Adding this credential to a session will enable TLS/IA, and will require an Application Phase after the TLS handshake (if the client support TLS/IA). Use gnutls_ia_enable() to toggle the TLS/IA mode.

Parameters

sc

is a pointer to a gnutls_ia_server_credentials_t structure.

 

Returns

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


gnutls_ia_set_client_avp_function ()

void
gnutls_ia_set_client_avp_function (gnutls_ia_client_credentials_t cred,
                                   gnutls_ia_avp_func avp_func);

gnutls_ia_set_client_avp_function is deprecated and should not be used in newly-written code.

Set the TLS/IA AVP callback handler used for the session.

The AVP callback is called to process AVPs received from the server, and to get a new AVP to send to the server.

The callback's function form is: int (*avp_func) (gnutls_session_t session, void *ptr, const char *last, size_t lastlen, char **next, size_t *nextlen);

The session parameter is the gnutls_session_t structure corresponding to the current session. The ptr parameter is the application hook pointer, set through gnutls_ia_set_client_avp_ptr(). The AVP received from the server is present in last of lastlen size, which will be NULL on the first invocation. The newly allocated output AVP to send to the server should be placed in *next of *nextlen size.

The callback may invoke gnutls_ia_permute_inner_secret() to mix any generated session keys with the TLS/IA inner secret.

Return 0 (GNUTLS_IA_APPLICATION_PAYLOAD) on success, or a negative error code to abort the TLS/IA handshake.

Note that the callback must use allocate the next parameter using gnutls_malloc(), because it is released via gnutls_free() by the TLS/IA handshake function.

Parameters

cred

is a gnutls_ia_client_credentials_t structure.

 

avp_func

is the callback function

 

gnutls_ia_set_client_avp_ptr ()

void
gnutls_ia_set_client_avp_ptr (gnutls_ia_client_credentials_t cred,
                              void *ptr);

gnutls_ia_set_client_avp_ptr is deprecated and should not be used in newly-written code.

Sets the pointer that will be provided to the TLS/IA callback function as the first argument.

Parameters

cred

is a gnutls_ia_client_credentials_t structure.

 

ptr

is the pointer

 

gnutls_ia_get_client_avp_ptr ()

void *
gnutls_ia_get_client_avp_ptr (gnutls_ia_client_credentials_t cred);

gnutls_ia_get_client_avp_ptr is deprecated and should not be used in newly-written code.

Returns the pointer that will be provided to the TLS/IA callback function as the first argument.

Parameters

cred

is a gnutls_ia_client_credentials_t structure.

 

Returns

The client callback data pointer.


gnutls_ia_set_server_avp_function ()

void
gnutls_ia_set_server_avp_function (gnutls_ia_server_credentials_t cred,
                                   gnutls_ia_avp_func avp_func);

gnutls_ia_set_server_avp_function is deprecated and should not be used in newly-written code.


gnutls_ia_set_server_avp_ptr ()

void
gnutls_ia_set_server_avp_ptr (gnutls_ia_server_credentials_t cred,
                              void *ptr);

gnutls_ia_set_server_avp_ptr is deprecated and should not be used in newly-written code.

Sets the pointer that will be provided to the TLS/IA callback function as the first argument.

Parameters

cred

is a gnutls_ia_client_credentials_t structure.

 

ptr

is the pointer

 

gnutls_ia_get_server_avp_ptr ()

void *
gnutls_ia_get_server_avp_ptr (gnutls_ia_server_credentials_t cred);

gnutls_ia_get_server_avp_ptr is deprecated and should not be used in newly-written code.

Returns the pointer that will be provided to the TLS/IA callback function as the first argument.

Parameters

cred

is a gnutls_ia_client_credentials_t structure.

 

Returns

The server callback data pointer.


gnutls_ia_handshake_p ()

int
gnutls_ia_handshake_p (gnutls_session_t session);

gnutls_ia_handshake_p is deprecated and should not be used in newly-written code.

Predicate to be used after gnutls_handshake() to decide whether to invoke gnutls_ia_handshake(). Usable by both clients and servers.

Parameters

session

is a gnutls_session_t structure.

 

Returns

non-zero if TLS/IA handshake is expected, zero otherwise.


gnutls_ia_handshake ()

int
gnutls_ia_handshake (gnutls_session_t session);

gnutls_ia_handshake is deprecated and should not be used in newly-written code.

Perform a TLS/IA handshake. This should be called after gnutls_handshake() iff gnutls_ia_handshake_p().

Parameters

session

is a gnutls_session_t structure.

 

Returns

On success, GNUTLS_E_SUCCESS (zero) is returned, otherwise an error code is returned.


gnutls_ia_permute_inner_secret ()

int
gnutls_ia_permute_inner_secret (gnutls_session_t session,
                                size_t session_keys_size,
                                const char *session_keys);

gnutls_ia_permute_inner_secret is deprecated and should not be used in newly-written code.

Permute the inner secret using the generated session keys.

This can be called in the TLS/IA AVP callback to mix any generated session keys with the TLS/IA inner secret.

Parameters

session

is a gnutls_session_t structure.

 

session_keys_size

Size of generated session keys (0 if none).

 

session_keys

Generated session keys, used to permute inner secret (NULL if none).

 

Returns

Return zero on success, or a negative error code.


gnutls_ia_endphase_send ()

int
gnutls_ia_endphase_send (gnutls_session_t session,
                         int final_p);

Send a TLS/IA end phase message.

In the client, this should only be used to acknowledge an end phase message sent by the server.

In the server, this can be called instead of gnutls_ia_send() if the server wishes to end an application phase.

Parameters

session

is a gnutls_session_t structure.

 

final_p

Set iff this should signal the final phase.

 

Returns

Return 0 on success, or an error code.


gnutls_ia_verify_endphase ()

int
gnutls_ia_verify_endphase (gnutls_session_t session,
                           const char *checksum);

Verify TLS/IA end phase checksum data. If verification fails, the GNUTLS_A_INNER_APPLICATION_VERIFICATION alert is sent to the other sie.

This function is called when gnutls_ia_recv() return GNUTLS_E_WARNING_IA_IPHF_RECEIVED or GNUTLS_E_WARNING_IA_FPHF_RECEIVED.

Parameters

session

is a gnutls_session_t structure.

 

checksum

12-byte checksum data, received from gnutls_ia_recv().

 

Returns

Return 0 on successful verification, or an error code. If the checksum verification of the end phase message fails, GNUTLS_E_IA_VERIFY_FAILED is returned.


gnutls_ia_send ()

ssize_t
gnutls_ia_send (gnutls_session_t session,
                const char *data,
                size_t sizeofdata);

Send TLS/IA application payload data. This function has the similar semantics with send(). The only difference is that it accepts a GnuTLS session, and uses different error codes.

The TLS/IA protocol is synchronous, so you cannot send more than one packet at a time. The client always send the first packet.

To finish an application phase in the server, use gnutls_ia_endphase_send(). The client cannot end an application phase unilaterally; rather, a client is required to respond with an endphase of its own if gnutls_ia_recv indicates that the server has sent one.

If the EINTR is returned by the internal push function (the default is send()} then GNUTLS_E_INTERRUPTED will be returned. If GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call this function again, with the same parameters; alternatively you could provide a NULL pointer for data, and 0 for size.

Parameters

session

is a gnutls_session_t structure.

 

data

contains the data to send

 

sizeofdata

is the length of the data

 

Returns

The number of bytes sent, or a negative error code.


gnutls_ia_recv ()

ssize_t
gnutls_ia_recv (gnutls_session_t session,
                char *data,
                size_t sizeofdata);

Receive TLS/IA data. This function has the similar semantics with recv(). The only difference is that it accepts a GnuTLS session, and uses different error codes.

If the server attempt to finish an application phase, this function will return GNUTLS_E_WARNING_IA_IPHF_RECEIVED or GNUTLS_E_WARNING_IA_FPHF_RECEIVED. The caller should then invoke gnutls_ia_verify_endphase(), and if it runs the client side, also send an endphase message of its own using gnutls_ia_endphase_send.

If EINTR is returned by the internal push function (the default is code {recv()}) then GNUTLS_E_INTERRUPTED will be returned. If GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call this function again, with the same parameters; alternatively you could provide a NULL pointer for data, and 0 for size.

Parameters

session

is a gnutls_session_t structure.

 

data

the buffer that the data will be read into, must hold >= 12 bytes.

 

sizeofdata

the number of requested bytes, must be >= 12.

 

Returns

The number of bytes received. A negative error code is returned in case of an error. The GNUTLS_E_WARNING_IA_IPHF_RECEIVED and GNUTLS_E_WARNING_IA_FPHF_RECEIVED errors are returned when an application phase finished message has been sent by the server.


gnutls_ia_generate_challenge ()

int
gnutls_ia_generate_challenge (gnutls_session_t session,
                              size_t buffer_size,
                              char *buffer);

gnutls_ia_generate_challenge is deprecated and should not be used in newly-written code.

Generate an application challenge that the client cannot control or predict, based on the TLS/IA inner secret.

Parameters

session

is a gnutls_session_t structure.

 

buffer_size

size of output buffer.

 

buffer

pre-allocated buffer to contain buffer_size bytes of output.

 

Returns

Returns 0 on success, or an negative error code.


gnutls_ia_extract_inner_secret ()

void
gnutls_ia_extract_inner_secret (gnutls_session_t session,
                                char *buffer);

gnutls_ia_extract_inner_secret is deprecated and should not be used in newly-written code.

Copy the 48 bytes large inner secret into the specified buffer

This function is typically used after the TLS/IA handshake has concluded. The TLS/IA inner secret can be used as input to a PRF to derive session keys. Do not use the inner secret directly as a session key, because for a resumed session that does not include an application phase, the inner secret will be identical to the inner secret in the original session. It is important to include, for example, the client and server randomness when deriving a sesssion key from the inner secret.

Parameters

session

is a gnutls_session_t structure.

 

buffer

pre-allocated buffer to hold 48 bytes of inner secret.

 

gnutls_ia_enable ()

void
gnutls_ia_enable (gnutls_session_t session,
                  int allow_skip_on_resume);

gnutls_ia_enable is deprecated and should not be used in newly-written code.

Specify whether we must advertise support for the TLS/IA extension during the handshake.

At the client side, we always advertise TLS/IA if gnutls_ia_enable was called before the handshake; at the server side, we also require that the client has advertised that it wants to run TLS/IA before including the advertisement, as required by the protocol.

Similarly, at the client side we always advertise that we allow TLS/IA to be skipped for resumed sessions if allow_skip_on_resume is non-zero; at the server side, we also require that the session is indeed resumable and that the client has also advertised that it allows TLS/IA to be skipped for resumed sessions.

After the TLS handshake, call gnutls_ia_handshake_p() to find out whether both parties agreed to do a TLS/IA handshake, before calling gnutls_ia_handshake() or one of the lower level gnutls_ia_* functions.

Parameters

session

is a gnutls_session_t structure.

 

allow_skip_on_resume

non-zero if local party allows one to skip the TLS/IA application phases for a resumed session.

 

gnutls_global_init_extra ()

int
gnutls_global_init_extra (void);

This function initializes the global state of gnutls-extra library to defaults.

Note that gnutls_global_init() has to be called before this function. If this function is not called then the gnutls-extra library will not be usable.

This function is not thread safe, see the discussion for gnutls_global_init() on how to deal with that.

Returns

On success, GNUTLS_E_SUCCESS (zero) is returned, otherwise an error code is returned.


gnutls_register_md5_handler ()

int
gnutls_register_md5_handler (void);

Register a non-libgcrypt based MD5 and HMAC-MD5 handler. This is useful if you run Libgcrypt in FIPS-mode. Normally TLS requires use of MD5, so without this you cannot use GnuTLS with libgcrypt in FIPS mode.

Returns

GNUTLS_E_SUCCESS on success, otherwise an error.

Since: 2.6.0


gnutls_extra_check_version ()

const char *
gnutls_extra_check_version (const char *req_version);

Check GnuTLS Extra Library version.

See GNUTLS_EXTRA_VERSION for a suitable req_version string.

Parameters

req_version

version string to compare with, or NULL.

 

Returns

Check that the version of the library is at minimum the one given as a string in req_version and return the actual version string of the library; return NULL if the condition is not met. If NULL is passed to this function no check is done and only the version string is returned.

Types and Values

GNUTLS_EXTRA_VERSION

#define GNUTLS_EXTRA_VERSION GNUTLS_VERSION


enum gnutls_ia_apptype_t

Enumeration of different certificate encoding formats.

Members

GNUTLS_IA_APPLICATION_PAYLOAD

TLS/IA application payload.

 

GNUTLS_IA_INTERMEDIATE_PHASE_FINISHED

TLS/IA intermediate phase finished.

 

GNUTLS_IA_FINAL_PHASE_FINISHED

TLS/IA final phase finished.