![]() |
![]() |
![]() |
GNU TLS API Reference Manual | ![]() |
---|---|---|---|---|
#define LIBGNUTLS_EXTRA_VERSION enum gnutls_ia_apptype_t; int (*gnutls_ia_avp_func) (gnutls_session_t session, void *ptr, const char *last, size_t lastlen, char **next, size_t *nextlen); void gnutls_ia_free_client_credentials (gnutls_ia_client_credentials_t sc); int gnutls_ia_allocate_client_credentials (gnutls_ia_client_credentials_t *sc); void gnutls_ia_free_server_credentials (gnutls_ia_server_credentials_t sc); int gnutls_ia_allocate_server_credentials (gnutls_ia_server_credentials_t *sc); void gnutls_ia_set_client_avp_function (gnutls_ia_client_credentials_t cred, gnutls_ia_avp_func avp_func); void gnutls_ia_set_client_avp_ptr (gnutls_ia_client_credentials_t cred, void *ptr); void* gnutls_ia_get_client_avp_ptr (gnutls_ia_client_credentials_tcred ); void gnutls_ia_set_server_avp_function (gnutls_ia_server_credentials_t cred, gnutls_ia_avp_func avp_func); void gnutls_ia_set_server_avp_ptr (gnutls_ia_server_credentials_t cred, void *ptr); void* gnutls_ia_get_server_avp_ptr (gnutls_ia_server_credentials_tcred ); int gnutls_ia_handshake_p (gnutls_session_t session); int gnutls_ia_handshake (gnutls_session_t session); int gnutls_ia_permute_inner_secret (gnutls_session_t session, size_t session_keys_size, const char *session_keys); int gnutls_ia_endphase_send (gnutls_session_t session, int final_p); int gnutls_ia_verify_endphase (gnutls_session_t session, const char *checksum); ssize_t gnutls_ia_send (gnutls_session_t session, const char *data, size_t sizeofdata); ssize_t gnutls_ia_recv (gnutls_session_t session, char *data, size_t sizeofdata); int gnutls_ia_generate_challenge (gnutls_session_t session, size_t buffer_size, char *buffer); void gnutls_ia_extract_inner_secret (gnutls_session_t session, char *buffer); void gnutls_ia_enable (gnutls_session_t session, int allow_skip_on_resume); int gnutls_global_init_extra (void); const char* gnutls_extra_check_version (const char *req_version);
typedef enum { GNUTLS_IA_APPLICATION_PAYLOAD = 0, GNUTLS_IA_INTERMEDIATE_PHASE_FINISHED = 1, GNUTLS_IA_FINAL_PHASE_FINISHED = 2 } gnutls_ia_apptype_t;
int (*gnutls_ia_avp_func) (gnutls_session_t session, void *ptr, const char *last, size_t lastlen, char **next, size_t *nextlen);
|
|
|
|
|
|
|
|
|
|
|
|
Returns : |
void gnutls_ia_free_client_credentials (gnutls_ia_client_credentials_t sc);
This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.
|
is an gnutls_ia_client_credentials_t structure. |
int gnutls_ia_allocate_client_credentials (gnutls_ia_client_credentials_t *sc);
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.
|
is a pointer to an gnutls_ia_server_credentials_t structure. |
Returns : |
0 on success. |
void gnutls_ia_free_server_credentials (gnutls_ia_server_credentials_t sc);
This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.
|
is an gnutls_ia_server_credentials_t structure. |
int gnutls_ia_allocate_server_credentials (gnutls_ia_server_credentials_t *sc);
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.
|
is a pointer to an gnutls_ia_server_credentials_t structure. |
Returns : |
0 on success. |
void gnutls_ia_set_client_avp_function (gnutls_ia_client_credentials_t cred, gnutls_ia_avp_func avp_func);
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.
|
is a gnutls_ia_client_credentials_t structure. |
|
is the callback function |
void gnutls_ia_set_client_avp_ptr (gnutls_ia_client_credentials_t cred, void *ptr);
Sets the pointer that will be provided to the TLS/IA callback function as the first argument.
|
is a gnutls_ia_client_credentials_t structure. |
|
is the pointer |
void* gnutls_ia_get_client_avp_ptr (gnutls_ia_client_credentials_tcred );
|
|
Returns : |
the pointer that will be provided to the TLS/IA callback function as the first argument. |
void gnutls_ia_set_server_avp_function (gnutls_ia_server_credentials_t cred, gnutls_ia_avp_func avp_func);
|
|
|
void gnutls_ia_set_server_avp_ptr (gnutls_ia_server_credentials_t cred, void *ptr);
Sets the pointer that will be provided to the TLS/IA callback function as the first argument.
|
is a gnutls_ia_client_credentials_t structure. |
|
is the pointer |
void* gnutls_ia_get_server_avp_ptr (gnutls_ia_server_credentials_tcred );
|
|
Returns : |
the pointer that will be provided to the TLS/IA callback function as the first argument. |
int gnutls_ia_handshake_p (gnutls_session_t session);
Predicate to be used after gnutls_handshake()
to decide whether to
invoke gnutls_ia_handshake()
. Usable by both clients and servers.
|
is a gnutls_session_t structure. |
Returns : |
non-zero if TLS/IA handshake is expected, zero otherwise. |
int gnutls_ia_handshake (gnutls_session_t session);
Perform a TLS/IA handshake. This should be called after
gnutls_handshake()
iff gnutls_ia_handshake_p()
.
Return 0 on success, or an error code.
|
is a gnutls_session_t structure. |
Returns : |
int gnutls_ia_permute_inner_secret (gnutls_session_t session, size_t session_keys_size, const char *session_keys);
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.
|
is a gnutls_session_t structure. |
|
Size of generated session keys (0 if none). |
|
Generated session keys, used to permute inner secret (NULL if none). |
Returns : |
Return zero on success, or a negative error code. |
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.
|
is a gnutls_session_t structure. |
|
Set iff this should signal the final phase. |
Returns : |
Return 0 on success, or an error code. |
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
.
|
is a gnutls_session_t structure. |
|
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.
|
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 is
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.
|
is a gnutls_session_t structure. |
|
contains the data to send |
|
is the length of the data |
Returns : |
the number of bytes sent, or a negative error code. |
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 is 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.
|
is a gnutls_session_t structure. |
|
the buffer that the data will be read into, must hold >= 12 bytes. |
|
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.
|
int gnutls_ia_generate_challenge (gnutls_session_t session, size_t buffer_size, char *buffer);
Generate an application challenge that the client cannot control or predict, based on the TLS/IA inner secret.
|
is a gnutls_session_t structure. |
|
size of output buffer. |
|
pre-allocated buffer to contain buffer_size bytes of output.
|
Returns : |
Returns 0 on success, or an negative error code. |
void gnutls_ia_extract_inner_secret (gnutls_session_t session, char *buffer);
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.
|
is a gnutls_session_t structure. |
|
pre-allocated buffer to hold 48 bytes of inner secret. |
void gnutls_ia_enable (gnutls_session_t session, int allow_skip_on_resume);
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.
|
is a gnutls_session_t structure. |
|
non-zero if local party allows to skip the TLS/IA application phases for a resumed session. |
int gnutls_global_init_extra (void);
This function initializes the global state of gnutls-extra library to defaults. Returns zero on success.
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.
Returns : |
const char* gnutls_extra_check_version (const char *req_version);
Check that the version of the gnutls-extra library is at minimum the requested one and return the version string; return NULL if the condition is not satisfied. If a NULL is passed to this function, no check is done, but the version string is simply returned.
|
the version to check |
Returns : |