Function
char *
gnutls_mac_get_name
(MACAlgorithm algorithm
)
Arguments
- MACAlgorithm algorithm
- is a MAC algorithm
Description
Returns an allocated (with malloc) string that contains the name
of the specified MAC algorithm.
Function
char *
gnutls_compression_get_name
(CompressionMethod algorithm
)
Arguments
- CompressionMethod algorithm
- is a Compression algorithm
Description
Returns a localy allocated (with malloc) pointer to a string that contains the name
of the specified compression algorithm.
Function
char *
gnutls_cipher_get_name
(BulkCipherAlgorithm algorithm
)
Arguments
- BulkCipherAlgorithm algorithm
- is an encryption algorithm
Description
Returns a localy allocated (with malloc) pointer to a string that contains the name
of the specified cipher.
Function
char *
gnutls_kx_get_name
(KXAlgorithm algorithm
)
Arguments
- KXAlgorithm algorithm
- is a key exchange algorithm
Description
Returns a localy allocated (with malloc) pointer to a string that contains the name
of the specified key exchange algorithm.
Function
int
gnutls_set_kx_cred
(GNUTLS_STATE state
, KXAlgorithm kx
, void* cred
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- KXAlgorithm kx
- is a key exchange algorithm
- void* cred
- is a pointer to a structure.
Description
Sets the needed credentials for the specified (in kx) authentication
algorithm. Eg username, password - or public and private keys etc.
The (void* cred) parameter is a structure that depends on the
specified kx algorithm and on the current state (client or server).
[ In order to minimize memory usage, and share credentials between
several threads gnutls keeps a pointer to cred, and not the whole cred
structure. Thus you will have to keep the structure allocated until
you call gnutls_deinit(). ]
For GNUTLS_KX_DH_ANON cred should be NULL in case of a client.
In case of a server it should be DH_ANON_SERVER_CREDENTIALS.
For GNUTLS_KX_SRP cred should be SRP_CLIENT_CREDENTIALS
in case of a client, and SRP_SERVER_CREDENTIALS, in case
of a server.
Function
const void*
gnutls_get_auth_info
(GNUTLS_STATE state
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
This function must be called after a succesful gnutls_handshake().
Returns a pointer to authentication information.
In case of GNUTLS_KX_ANON returns a pointer to DH_ANON_AUTH_INFO;
In case of GNUTLS_KX_SRP returns a pointer to structure SRP_AUTH_INFO;
Function
int
gnutls_check_pending
(GNUTLS_STATE state
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
This function checks if there are any data to receive
in the gnutls buffers. Returns the size of that data or 0.
Notice that you may also use select() to check for data in
the TCP connection, instead of this function.
(gnutls leaves some data in the tcp buffer in order for select
to work).
Function
int
gnutls_set_lowat
(GNUTLS_STATE state
, int num
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- int num
- is the low water value.
Description
Used to set the lowat value in order for select to check
if there are pending data to socket buffer. Used only
if you have changed the default low water value (default is 1).
Normally you will not need that function.
Function
int
gnutls_init
(GNUTLS_STATE * state
, ConnectionEnd con_end
)
Arguments
- GNUTLS_STATE * state
- is a pointer to a GNUTLS_STATE structure.
- ConnectionEnd con_end
- is used to indicate if this state is to be used for server or
client. Can be one of GNUTLS_CLIENT and GNUTLS_SERVER.
Description
This function initializes the current state to null. Every state
must be initialized before use, so internal structures can be allocated.
This function allocates structures which can only be free'd
by calling gnutls_deinit(). Returns zero on success.
Function
int
gnutls_deinit
(GNUTLS_STATE state
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
This function clears all buffers associated with the state.
Function
int
gnutls_close
(int cd
, GNUTLS_STATE state
)
Arguments
- int cd
- is a connection descriptor.
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
Terminates the current TLS/SSL connection. If the return value is 0
you may continue using the TCP connection.
Function
BulkCipherAlgorithm
gnutls_get_current_cipher
(GNUTLS_STATE state
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
Returns the currently used cipher.
Function
KXAlgorithm
gnutls_get_current_kx
(GNUTLS_STATE state
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
Returns the key exchange algorithm used in the last handshake.
Function
MACAlgorithm
gnutls_get_current_mac_algorithm
(GNUTLS_STATE state
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
Returns the currently used mac algorithm.
Function
CompressionMethod
gnutls_get_current_compression_method
(GNUTLS_STATE state
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
Returns the currently used compression method.
Function
AlertDescription
gnutls_get_last_alert
(GNUTLS_STATE state
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
Returns the last alert number received. This function
should be called if GNUTLS_E_WARNING_ALERT_RECEIVED or
GNUTLS_E_FATAL_ALERT_RECEIVED has been returned by a gnutls function.
The peer may send alerts if he thinks some things were not
right. Check gnutls.h for the available alert descriptions.
Function
ssize_t
gnutls_send
(int cd
, GNUTLS_STATE state
, const void * data
, size_t sizeofdata
, int flags
)
Arguments
- int cd
- is a connection descriptor
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- const void * data
- contains the data to send
- size_t sizeofdata
- is the length of the data
- int flags
- contains the flags to pass to send() function.
Description
This function has the same semantics as send() has. The only
difference is that is accepts a GNUTLS state. Currently flags cannot
be anything except 0.
Function
ssize_t
gnutls_recv
(int cd
, GNUTLS_STATE state
, void * data
, size_t sizeofdata
, int flags
)
Arguments
- int cd
- is a connection descriptor
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- void * data
- contains the data to send
- size_t sizeofdata
- is the length of the data
- int flags
- contains the flags to pass to recv() function.
Description
This function has the same semantics as recv() has. The only
difference is that is accepts a GNUTLS state. Flags are the flags
passed to recv() and should be used with care in gnutls.
The only acceptable flag is currently MSG_DONTWAIT. In that case,
if the socket is set to non blocking IO it will return GNUTLS_E_AGAIN,
if there are no data in the socket.
Function
ssize_t
gnutls_write
(int cd
, GNUTLS_STATE state
, const void * data
, size_t sizeofdata
)
Arguments
- int cd
- is a connection descriptor
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- const void * data
- contains the data to send
- size_t sizeofdata
- is the length of the data
Description
This function has the same semantics as write() has. The only
difference is that is accepts a GNUTLS state.
Function
ssize_t
gnutls_read
(int cd
, GNUTLS_STATE state
, void * data
, size_t sizeofdata
)
Arguments
- int cd
- is a connection descriptor
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- void * data
- contains the data to send
- size_t sizeofdata
- is the length of the data
Description
This function has the same semantics as read() has. The only
difference is that is accepts a GNUTLS state.
Function
int
gnutls_set_cache_expiration
(GNUTLS_STATE state
, int seconds
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- int seconds
- is the number of seconds.
Description
Sets the expiration time for resumed sessions. The default is 3600 (one hour)
at the time writing this.
Function
int
gnutls_set_db_name
(GNUTLS_STATE state
, char* filename
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- char* filename
- is the filename for the database
Description
Sets the name of the (gdbm) database to be used to keep
the sessions to be resumed. This function also creates the database
- if it does not exist - and opens it for reading.
Function
int
gnutls_clean_db
(GNUTLS_STATE state
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
This function Deletes all expired records in the db. This db may become huge
if this function is not called.
Function
int
gnutls_is_fatal_error
(int error
)
Arguments
- int error
- is an error returned by a gnutls function. Error is always a negative value.
Description
If a function returns a negative value you may feed that value
to this function to see if it is fatal. Returns 1 for a fatal
error 0 otherwise. However you may want to check the
error code manualy, since some non-fatal errors to the protocol
may be fatal for you (your program).
Function
void
gnutls_perror
(int error
)
Arguments
- int error
- is an error returned by a gnutls function. Error is always a negative value.
Description
This function is like perror(). However it accepts an error returned by a gnutls
function.
Function
char*
gnutls_strerror
(int error
)
Arguments
- int error
- is an error returned by a gnutls function. Error is always a negative value.
Description
This function is like strerror(). However it accepts an error returned by a gnutls
function. gnutls_strerror() returns a malloc'ed value thus
it should be free'd.
Function
int
gnutls_send_hello_request
(int cd
, GNUTLS_STATE state
)
Arguments
- int cd
- is a connection descriptor, as returned by socket().
- GNUTLS_STATE state
- is a a GNUTLS_STATE structure.
Description
This function will renegotiate security parameters with the
client. This should only be called in case of a server.
If the client does not wish to renegotiate parameters he
will reply with an alert message, thus the return code will be
GNUTLS_E_WARNING_ALERT_RECEIVED and the alert will be
GNUTLS_NO_RENEGOTIATION.
Function
int
gnutls_handshake
(int cd
, GNUTLS_STATE state
)
Arguments
- int cd
- is a connection descriptor, as returned by socket().
- GNUTLS_STATE state
- is a a GNUTLS_STATE structure.
Description
This function does the handshake of the TLS/SSL protocol,
and initializes the TLS connection. Here the identity of the peer
is checked automatically.
This function will fail if any problem is encountered,
and the connection should be terminated.
Function
int
gnutls_handshake_begin
(int cd
, GNUTLS_STATE state
)
Arguments
- int cd
- is a connection descriptor, as returned by socket().
- GNUTLS_STATE state
- is a a GNUTLS_STATE structure.
Description
This function initiates the handshake of the TLS/SSL protocol.
Here we will receive - if requested and supported by the ciphersuite -
the peer's certificate.
This function will fail if any problem in the handshake is encountered.
However this failure will not be fatal. However you may choose to
continue the handshake - eg. even if the certificate cannot
be verified- by calling gnutls_handshake_finish().
Function
int
gnutls_handshake_finish
(int cd
, GNUTLS_STATE state
)
Arguments
- int cd
- is a connection descriptor, as returned by socket().
- GNUTLS_STATE state
- is a a GNUTLS_STATE structure.
Description
This function does the final stuff of the handshake protocol.
You should call it only if you used gnutls_handshake_begin() and
you have somehow verified the identity of the peer.
This function will fail if any problem is encountered.
Function
void
gnutls_set_cipher_priority
(GNUTLS_STATE state
, ...
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
@...: is a 0 terminated list of BulkCipherAlgorithm elements.
- ...
- -- undescribed --
Description
Sets the priority on the ciphers supported by gnutls.
Priority is higher for ciphers specified before others.
After specifying the ciphers you want, you should add 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.
Function
void
gnutls_set_kx_priority
(GNUTLS_STATE state
, ...
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
@...: is a 0 terminated list of KXAlgorithm elements.
- ...
- -- undescribed --
Description
Sets the priority on the key exchange algorithms supported by gnutls.
Priority is higher for algorithms specified before others.
After specifying the algorithms you want, you should add 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.
Function
void
gnutls_set_mac_priority
(GNUTLS_STATE state
, ...
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
@...: is a 0 terminated list of MACAlgorithm elements.
- ...
- -- undescribed --
Description
Sets the priority on the mac algorithms supported by gnutls.
Priority is higher for algorithms specified before others.
After specifying the algorithms you want, you should add 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.
Function
void
gnutls_set_compression_priority
(GNUTLS_STATE state
, ...
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
@...: is a 0 terminated list of CompressionMethod elements.
- ...
- -- undescribed --
Description
Sets the priority on the compression algorithms supported by gnutls.
Priority is higher for algorithms specified before others.
After specifying the algorithms you want, you should add 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.
Function
int
gnutls_get_current_session
(GNUTLS_STATE state
, opaque* session
, int * session_size
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- opaque* session
- is a pointer to space to hold the session.
- int * session_size
- is the session's size, or it will be set by the function.
Description
Function
int
gnutls_get_current_session_id
(GNUTLS_STATE state
, void* session
, int * session_size
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- void* session
- is a pointer to space to hold the session id.
- int * session_size
- is the session id's size, or it will be set by the function.
Description
Returns the current session id. This can be used if you want to check if
the next session you tried to resume was actually resumed.
(resumed sessions have the same sessionID with the first session)
Session id is some data set by the server, that identify the current session.
In TLS 1.0 session id should not be more than 32 bytes.
Function
int
gnutls_set_current_session
(GNUTLS_STATE state
, opaque* session
, int session_size
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- opaque* session
- is a pointer to space to hold the session.
- int session_size
- is the session's size
Description
Sets all session parameters - in order to support resuming
session must be the one returned by gnutls_get_current_session();
This function should be called before gnutls_handshake_begin() or gnutls_handshake().
Keep in mind that session resuming is advisory. The server may
choose not to resume the session, thus a full handshake will be
performed.