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
char *
gnutls_version_get_name
(GNUTLS_Version version
)
Arguments
- GNUTLS_Version version
- is a (gnutls) version number
Description
Returns an allocated (with malloc) string that contains the name
of the specified TLS version.
Function
int
gnutls_set_cred
(GNUTLS_STATE state
, CredType type
, void* cred
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- CredType type
- is the type of the credentials
- void* cred
- is a pointer to a structure.
Description
Sets the needed credentials for the specified type.
Eg username, password - or public and private keys etc.
The (void* cred) parameter is a structure that depends on the
specified type 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_ANON cred should be NULL in case of a client.
In case of a server it should be ANON_SERVER_CREDENTIALS.
For GNUTLS_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. That information
is data obtained by the handshake protocol, the key exchange algorithm,
and the TLS extensions messages.
In case of GNUTLS_ANON returns a pointer to ANON_AUTH_INFO;
In case of GNUTLS_X509PKI returns a pointer to structure X509PKI_AUTH_INFO;
In case of GNUTLS_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
void
gnutls_free_x509_sc
(X509PKI_SERVER_CREDENTIALS sc
)
Arguments
- X509PKI_SERVER_CREDENTIALS sc
- is an X509PKI_SERVER_CREDENTIALS structure.
Description
This structure is complex enough to manipulate directly thus
this helper function is provided in order to free (deallocate)
the structure.
Function
int
gnutls_allocate_x509_sc
(X509PKI_SERVER_CREDENTIALS * res
, char * CERTFILE
, char * KEYFILE
)
Arguments
- X509PKI_SERVER_CREDENTIALS * res
- is a pointer to an X509PKI_SERVER_CREDENTIALS structure.
- char * CERTFILE
- is the name of a PEM encoded certificate file
- char * KEYFILE
- is the name of a PEM encoded key file
Description
This structure is complex enough to manipulate directly thus
this helper function is provided in order to allocate
the structure from the given keys.
FIXME
does not support multiple keys yet.
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 resumed sessions' database.
This database may become huge if this function is not called.
(this function is also quite expensive)
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_global_init
(char* PKIX
, char* PKCS1
)
Arguments
- char* PKIX
- -- undescribed --
- char* PKCS1
- -- undescribed --
Description
This function initializes the global state to defaults.
Every gnutls application has a global state which holds common parameters
shared by gnutls state structures.
You must call gnutls_global_deinit() when gnutls usage is no longer needed
Returns zero on success.
Function
void
gnutls_global_deinit
()
Arguments
Description
Function
int
gnutls_rehandshake
(SOCKET cd
, GNUTLS_STATE state
)
Arguments
- SOCKET 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
(SOCKET cd
, GNUTLS_STATE state
)
Arguments
- SOCKET 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
void
gnutls_set_cipher_priority
(GNUTLS_STATE state
, LIST
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- LIST
- is a 0 terminated list of BulkCipherAlgorithm elements.
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
, LIST
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- LIST
- is a 0 terminated list of KXAlgorithm elements.
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
, LIST
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- LIST
- is a 0 terminated list of MACAlgorithm elements.
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
, LIST
)
Arguments
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
- LIST
- is a 0 terminated list of CompressionMethod elements.
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_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_bye
(SOCKET cd
, GNUTLS_STATE state
)
Arguments
- SOCKET 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. The connection should
have been initiated using gnutls_handshake() or similar function.
Function
int
gnutls_bye_nowait
(SOCKET cd
, GNUTLS_STATE state
)
Arguments
- SOCKET cd
- is a connection descriptor.
- GNUTLS_STATE state
- is a GNUTLS_STATE structure.
Description
Terminates the current TLS/SSL connection. The connection should
have been initiated using gnutls_handshake() or similar function.
This function does not wait for the other peer to close the TLS
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
(SOCKET cd
, GNUTLS_STATE state
, const void * data
, size_t sizeofdata
, int flags
)
Arguments
- SOCKET 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
(SOCKET cd
, GNUTLS_STATE state
, void * data
, size_t sizeofdata
, int flags
)
Arguments
- SOCKET 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
(SOCKET cd
, GNUTLS_STATE state
, const void * data
, size_t sizeofdata
)
Arguments
- SOCKET 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
(SOCKET cd
, GNUTLS_STATE state
, void * data
, size_t sizeofdata
)
Arguments
- SOCKET 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_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().
Keep in mind that session resuming is advisory. The server may
choose not to resume the session, thus a full handshake will be
performed.