info gnutls

E.2 High level TLS API

The prototypes for the following functions lie in ‘gnutls/xssl.h’.

xssl_client_init

Function: int xssl_client_init (xssl_t * isb, const char * hostname, const char * service, gnutls_transport_ptr fd, const char * priority, xssl_cred_t cred, unsigned int * status, unsigned int flags)

isb: is a pointer to a xssl_t structure.

hostname: The name of the host to connect to

service: The name of the host to connect to

fd: a socket descriptor

priority: A priority string to use (use NULL for default)

cred: A credentials structure

status: An authentication failure status

flags: should be zero or GNUTLS_SBUF_WRITE_FLUSHES

This function initializes a xssl_t structure. If the flag GNUTLS_SBUF_WRITE_FLUSHES is set then xssl_queue() will flush when the maximum data size for a record is reached.

If peer verification fails then GNUTLS_E_AUTH_ERROR is returned.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

Since: 3.1.7

xssl_cred_deinit

Function: void xssl_cred_deinit (xssl_cred_t cred)

cred: is a xssl_cred_t structure.

This function deinitializes a xssl_cred_t structure.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

Since: 3.1.7

xssl_cred_init

Function: int xssl_cred_init (xssl_cred_t * c, unsigned vflags, gnutls_cinput_st * aux, unsigned aux_size)

c: is a pointer to xssl_cred_t structure.

vflags: the requested peer verification methods

aux: Auxilary data to input any required CA certificate etc.

aux_size: the number of the auxillary data provided

This function initializes X.509 certificates in a xssl_cred_t structure.

The ca_file and crl_file are required only if vflags includes GNUTLS_VMETHOD_GIVEN_CAS . The tofu_file may be set if GNUTLS_VMETHOD_TOFU is specified.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

Since: 3.1.7

xssl_deinit

Function: void xssl_deinit (xssl_t sb)

sb: is a xssl_t structure.

This function clears all buffers associated with the sb structure. The GnuTLS session associated with the structure is left intact.

Since: 3.1.7

xssl_flush

Function: ssize_t xssl_flush (xssl_t sb)

sb: is a xssl_t structure.

This function flushes the buffer sb . All the data stored are transmitted.

This function must only be used with blocking sockets.

Returns: On success, the number of bytes sent, otherwise a negative error code.

Since: 3.1.7

xssl_getdelim

Function: ssize_t xssl_getdelim (xssl_t sbuf, char ** lineptr, size_t * n, int delimiter)

sbuf: – undescribed –

lineptr: a pointer.

n: The size of lineptr .

delimiter: The delimiter to stop reading at.

Read up to (and including) a delimiter from &sb into *LINEPTR (and NUL-terminate it). lineptr is a pointer returned from gnutls_malloc() (or NULL ), pointing to n characters of space. It is realloc’ed as necessary.

Only fatal errors are returned by this function.

Returns the number of characters read (not including the null terminator), or a negative error code on error.

Since: 3.1.7

xssl_get_session

Function: gnutls_session_t xssl_get_session (xssl_t sb)

sb: is a xssl_t structure.

Returns: The associated session or NULL .

Since: 3.1.7

xssl_printf

Function: ssize_t xssl_printf (xssl_t sb, const char * fmt, ...)

sb: is a xssl_t structure.

fmt: printf-style format

...: – undescribed –

This function allows writing to a xssl_t using printf style arguments.

This function must only be used with blocking sockets.

Returns: On success, the number of bytes written is returned, otherwise an error code is returned.

Since: 3.1.7

xssl_read

Function: ssize_t xssl_read (xssl_t sb, void * data, size_t data_size)

sb: is a xssl_t structure.

data: the buffer that the data will be read into

data_size: the number of requested bytes

This function receives data from the underlying session. Only fatal errors are returned by this function.

Returns: The number of bytes received and zero on EOF (for stream connections) or a negative error code.

Since: 3.1.7

xssl_server_init

Function: int xssl_server_init (xssl_t * isb, gnutls_transport_ptr fd, const char * priority, xssl_cred_t cred, unsigned int * status, unsigned int flags)

isb: is a pointer to a xssl_t structure.

fd: a socket descriptor

priority: A priority string to use (use NULL for default)

cred: A credentials structure

status: An authentication failure status

flags: should be zero or GNUTLS_SBUF_WRITE_FLUSHES

This function initializes a xssl_t structure. If the flag GNUTLS_SBUF_WRITE_FLUSHES is set then xssl_queue() will flush when the maximum data size for a record is reached.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

Since: 3.1.7

xssl_sinit

Function: int xssl_sinit (xssl_t * isb, gnutls_session_t session, unsigned int flags)

isb: is a pointer to a xssl_t structure.

session: a GnuTLS session

flags: should be zero or GNUTLS_SBUF_WRITE_FLUSHES

This function initializes a xssl_t structure associated with the provided session. If the flag GNUTLS_SBUF_WRITE_FLUSHES is set then xssl_queue() will flush when the maximum data size for a record is reached.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

Since: 3.1.7

xssl_write

Function: ssize_t xssl_write (xssl_t sb, const void * data, size_t data_size)

sb: is a xssl_t structure.

data: contains the data to send

data_size: is the length of the data

This function is the buffered equivalent of gnutls_record_send() . Instead of sending the data immediately the data are buffered until xssl_queue() is called, or if the flag GNUTLS_SBUF_WRITE_FLUSHES is set, until the number of bytes for a full record is reached.

This function must only be used with blocking sockets.

Returns: On success, the number of bytes written is returned, otherwise an error code is returned.

Since: 3.1.7

This document was generated on February 9, 2014 using texi2html 5.0.