[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
9.5 TLS Inner Application (TLS/IA) Functions
The following functions are used for TLS Inner Application (TLS/IA). Their prototypes lie in ‘gnutls/extra.h’. You need to link with ‘libgnutls-extra’ to be able to use these functions (see section GnuTLS-extra Functions).
The typical control flow in an TLS/IA client (that would not require an Application Phase for resumed sessions) would be similar to the following:
int client_avp (gnuls_session_t *session, void *ptr, const char *last, size_t lastlen, char **new, size_t *newlen) { ... } ... int main () { gnutls_ia_client_credentials_t iacred; ... gnutls_init (&session, GNUTLS_CLIENT); ... /* Enable TLS/IA. */ gnutls_ia_allocate_client_credentials(&iacred); gnutls_ia_set_client_avp_function(iacred, client_avp); gnutls_credentials_set (session, GNUTLS_CRD_IA, iacred); ... ret = gnutls_handshake (session); // Error handling... ... if (gnutls_ia_handshake_p (session)) { ret = gnutls_ia_handshake (session); // Error handling... ... |
See below for detailed descriptions of all the functions used above.
The function client_avp
would have to be implemented by your
application. The function is responsible for handling the AVP data.
See gnutls_ia_set_client_avp_function
below for more
information on how that function should be implemented.
The control flow in a typical server is similar to the above, use
gnutls_ia_server_credentials_t
instead of
gnutls_ia_client_credentials_t
, and replace the call to the
client functions with the corresponding server functions.
gnutls_ia_allocate_client_credentials
- Function: int gnutls_ia_allocate_client_credentials (gnutls_ia_client_credentials_t * sc)
sc: is a pointer to a
gnutls_ia_server_credentials_t
structure.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_require_inner_phase()
to toggle the TLS/IA mode.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise an error code is returned.
gnutls_ia_allocate_server_credentials
- Function: int gnutls_ia_allocate_server_credentials (gnutls_ia_server_credentials_t * sc)
sc: is a pointer to a
gnutls_ia_server_credentials_t
structure.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_require_inner_phase()
to toggle the TLS/IA mode.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise an error code is returned.
gnutls_ia_enable
- Function: void gnutls_ia_enable (gnutls_session_t session, int allow_skip_on_resume)
session: is a
gnutls_session_t
structure.allow_skip_on_resume: non-zero if local party allows to skip the TLS/IA application phases for a resumed session.
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 callinggnutls_ia_handshake()
or one of the lower level gnutls_ia_* functions.
gnutls_ia_endphase_send
- Function: int gnutls_ia_endphase_send (gnutls_session_t session, int final_p)
session: is a
gnutls_session_t
structure.final_p: Set iff this should signal the final phase.
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.Return value: Return 0 on success, or an error code.
gnutls_ia_extract_inner_secret
- Function: void gnutls_ia_extract_inner_secret (gnutls_session_t session, char * buffer)
session: is a
gnutls_session_t
structure.buffer: pre-allocated buffer to hold 48 bytes of inner secret.
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.
gnutls_ia_free_client_credentials
- Function: void gnutls_ia_free_client_credentials (gnutls_ia_client_credentials_t sc)
sc: is a
gnutls_ia_client_credentials_t
structure.This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.
gnutls_ia_free_server_credentials
- Function: void gnutls_ia_free_server_credentials (gnutls_ia_server_credentials_t sc)
sc: is a
gnutls_ia_server_credentials_t
structure.This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.
gnutls_ia_generate_challenge
- Function: int gnutls_ia_generate_challenge (gnutls_session_t session, size_t buffer_size, char * buffer)
session: is a
gnutls_session_t
structure.buffer_size: size of output buffer.
buffer: pre-allocated buffer to contain
buffer_size
bytes of output.Generate an application challenge that the client cannot control or predict, based on the TLS/IA inner secret.
Return value: Returns 0 on success, or an negative error code.
gnutls_ia_get_client_avp_ptr
- Function: void * gnutls_ia_get_client_avp_ptr (gnutls_ia_client_credentials_t cred)
cred: is a
gnutls_ia_client_credentials_t
structure.Returns the pointer that will be provided to the TLS/IA callback function as the first argument.
Returns: The client callback data pointer.
gnutls_ia_get_server_avp_ptr
- Function: void * gnutls_ia_get_server_avp_ptr (gnutls_ia_server_credentials_t cred)
cred: is a
gnutls_ia_client_credentials_t
structure.Returns the pointer that will be provided to the TLS/IA callback function as the first argument.
Returns: The server callback data pointer.
gnutls_ia_handshake_p
- Function: int gnutls_ia_handshake_p (gnutls_session_t session)
session: is a
gnutls_session_t
structure.Predicate to be used after
gnutls_handshake()
to decide whether to invokegnutls_ia_handshake()
. Usable by both clients and servers.Return value: non-zero if TLS/IA handshake is expected, zero otherwise.
gnutls_ia_handshake
- Function: int gnutls_ia_handshake (gnutls_session_t session)
session: is a
gnutls_session_t
structure.Perform a TLS/IA handshake. This should be called after
gnutls_handshake()
iffgnutls_ia_handshake_p()
.Returns: On success,
GNUTLS_E_SUCCESS
(zero) is returned, otherwise an error code is returned.
gnutls_ia_permute_inner_secret
- Function: int gnutls_ia_permute_inner_secret (gnutls_session_t session, size_t session_keys_size, const char * session_keys)
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).
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.
Return value: Return zero on success, or a negative error code.
gnutls_ia_recv
- Function: ssize_t gnutls_ia_recv (gnutls_session_t session, char * data, size_t sizeofdata)
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.
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
orGNUTLS_E_WARNING_IA_FPHF_RECEIVED
. The caller should then invokegnutls_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.Returns: The number of bytes received. A negative error code is returned in case of an error. The
GNUTLS_E_WARNING_IA_IPHF_RECEIVED
andGNUTLS_E_WARNING_IA_FPHF_RECEIVED
errors are returned when an application phase finished message has been sent by the server.
gnutls_ia_send
- Function: ssize_t gnutls_ia_send (gnutls_session_t session, const char * data, size_t sizeofdata)
session: is a
gnutls_session_t
structure.data: contains the data to send
sizeofdata: is the length of the data
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()
} thenGNUTLS_E_INTERRUPTED
will be returned. IfGNUTLS_E_INTERRUPTED
orGNUTLS_E_AGAIN
is returned, you must call this function again, with the same parameters; alternatively you could provide aNULL
pointer for data, and 0 for size.Returns: The number of bytes sent, or a negative error code.
gnutls_ia_set_client_avp_function
- Function: void gnutls_ia_set_client_avp_function (gnutls_ia_client_credentials_t cred, gnutls_ia_avp_func avp_func)
cred: is a
gnutls_ia_client_credentials_t
structure.avp_func: is the callback function
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 thegnutls_session_t
structure corresponding to the current session. Theptr
parameter is the application hook pointer, set throughgnutls_ia_set_client_avp_ptr()
. The AVP received from the server is present inlast
oflastlen
size, which will beNULL
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 usinggnutls_malloc()
, because it is released viagnutls_free()
by the TLS/IA handshake function.
gnutls_ia_set_client_avp_ptr
- Function: void gnutls_ia_set_client_avp_ptr (gnutls_ia_client_credentials_t cred, void * ptr)
cred: is a
gnutls_ia_client_credentials_t
structure.ptr: is the pointer
Sets the pointer that will be provided to the TLS/IA callback function as the first argument.
gnutls_ia_set_server_avp_function
- Function: void gnutls_ia_set_server_avp_function (gnutls_ia_server_credentials_t cred, gnutls_ia_avp_func avp_func)
cred: is a
gnutls_ia_server_credentials_t
structure.Set the TLS/IA AVP callback handler used for the session.
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 thegnutls_session_t
structure corresponding to the current session. Theptr
parameter is the application hook pointer, set throughgnutls_ia_set_server_avp_ptr()
. The AVP received from the client is present inlast
oflastlen
size. The newly allocated output AVP to send to the client should be placed in *next
of *nextlen
size.The AVP callback is called to process incoming AVPs from the client, and to get a new AVP to send to the client. It can also be used to instruct the TLS/IA handshake to do go into the Intermediate or Final phases. It return a negative error code, or a
gnutls_ia_apptype_t
message type.The callback may invoke
gnutls_ia_permute_inner_secret()
to mix any generated session keys with the TLS/IA inner secret.Specifically, return
GNUTLS_IA_APPLICATION_PAYLOAD
(0) to send another AVP to the client, returnGNUTLS_IA_INTERMEDIATE_PHASE_FINISHED
(1) to indicate that an IntermediatePhaseFinished message should be sent, and returnGNUTLS_IA_FINAL_PHASE_FINISHED
(2) to indicate that an FinalPhaseFinished message should be sent. In the last two cases, the contents of thenext
andnextlen
parameter is not used.Note that the callback must use allocate the
next
parameter usinggnutls_malloc()
, because it is released viagnutls_free()
by the TLS/IA handshake function.
gnutls_ia_set_server_avp_ptr
- Function: void gnutls_ia_set_server_avp_ptr (gnutls_ia_server_credentials_t cred, void * ptr)
cred: is a
gnutls_ia_client_credentials_t
structure.ptr: is the pointer
Sets the pointer that will be provided to the TLS/IA callback function as the first argument.
gnutls_ia_verify_endphase
- Function: int gnutls_ia_verify_endphase (gnutls_session_t session, const char * checksum)
session: is a
gnutls_session_t
structure.checksum: 12-byte checksum data, received from
gnutls_ia_recv()
.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()
returnGNUTLS_E_WARNING_IA_IPHF_RECEIVED
orGNUTLS_E_WARNING_IA_FPHF_RECEIVED
.Return value: 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |