[ this is mostly outdated... you should check the mailing list archives  ]
[ at http://lists.gnupg.org for more information on new functions. sorry ]

Last update: 15 Nov 2000


(The functions which are prefixed by '_' are internal functions, not intended
to be included in the API)

GENERIC FUNCTIONS:

gnutls_init(GNUTLS_STATE*, ConnectionEnd):
	This function just initializes the state to null. (null encryption,
	null mac etc.)

_gnutls_set_cipher( GNUTLS_STATE, BulkCipherAlgorithm):
	This function sets the BulkCipherAlgorithm to the pending state.

_gnutls_set_compression(GNUTLS_STATE, CompressionMethod):
	This function sets the CompressionMethod to the pending state.

_gnutls_set_mac( GNUTLS_STATE, MACAlgorithm):
	This function sets the MACAlgorithm to the pending state.

_gnutls_set_keys( GNUTLS_STATE):
	This function is to be called after handshake, when master_secret, 
	client_random and server_random have been initialized.
	This function creates the keys and stores them into pending state.

_gnutls_connection_state_init( GNUTLS_STATE):
	This function sets the current connection state to conform with the
	security parameters(pending state), and initializes encryption.
	This function is to be called after a successful handshake. It
	sets the algorithms (mac,cipher etc) from the handshake, and setups
	all the keys and IV needed (uses the previous functions).

gnutls_send( int desc, GNUTLS_STATE, char* data, int datalen):
gnutls_recv( int desc, GNUTLS_STATE, char* data, int datalen):
	These functions behave exactly like write()/read(). The 
	only difference is that they accept, the gnutls_state.
	They are to transfer data, under the current state.

gnutls_deinit( GNUTLS_STATE* state):
	This functions clears all buffers associated with the state.

gnutls_set_cipher_priority( ...)
	This function accepts an integer and a list of algorithms.
	The algorithms used here are defined in gnutls.h.
	If the algorithm is not specified here then it will not
	be used in the handshake. eg
	gnutls_set_cipher_priority(1, GNUTLS_3DES)

gnutls_set_mac_priority( ...)
	This function accepts an integer and a list of algorithms.
	If the algorithm is not specified here then it will not
	be used in the handshake. eg:
	gnutls_set_mac_priority(2, GNUTLS_MAC_SHA, GNUTLS_MAC_MD5);

gnutls_set_kx_priority( ...)
	This function accepts an integer and a list of key exchange algorithms.
	If the algorithm is not specified here then it will not
	be used in the handshake. eg:
	gnutls_set_kx_priority( 1, GNUTLS_KX_ANON_DH);

void gnutls_set_current_version(GNUTLS_STATE state, GNUTLS_Version);
	sets the current version to the one specified. GNUTLS_Version has three
	fields. Local is used for TLS versions that do not support the standard 
	2 byte version. It is zero for TLS 1.0 (3.1). If local is 0 Major and Minor 
	are used as in TLS.


HANDSHAKE FUNCTIONS:

[taken from a message in gnutls-dev]





HANDSHAKE FUNCTIONS:

[taken from a message in gnutls-dev]

Well, the main function in the handshake protocol is gnutls_handshake().
This does actually everything. Let's say we are on the client side.
The client sends or receives hello messages (by calling gnutls_send_hello() to 
send a hello message, or _gnutls_recv_handshake(cd, state, NULL, NULL, GNUTLS_SERVER_HELLO),
to receive one. 

_gnutls_recv_handshake(...) will receive handshake messages of the
given type, and will pass the message to the right place in order
to be processed. Eg. for the SERVER_HELLO message (if it is valid) 
it will be send to _gnutls_recv_hello()).

Since we have a global state, all these functions do use the global
variables to determine what to send. Eg gnutls_send_hello() does not require
any parameters, and will determine from the state an from the available
cipher suites which to use (currently there is no way for the user 
to select the priority of cipher suites).

Then depending on the algorithm suite we should receive server
certificates, which is not implemented (dh-anon does not use that).

After that we receive the key exchange message of server by calling:
_gnutls_recv_server_kx_message(). If that message is not required by
the cipher suite, that function does nothing. (what is required and not,
can be set in gnutls_algorithms.c and gnutls_algorithms.h).

After that the client waits for the server hello done message by
calling: _gnutls_recv_handshake(cd, state, NULL, NULL, GNUTLS_SERVER_HELLO_DONE);

After that we should send the client certificates (also not implemented).
This is the time for the client to send the key exchange message
by calling: _gnutls_send_client_kx_message().

If everything was right we send the change cipher spec packet by
calling: _gnutls_send_change_cipher_spec().

This is the time to start encryption (initialize the state) with:
_gnutls_connection_state_init(state). This function initilizes and starts
encryption (so it needs secrets and random numbers to have been negotiated)

Then we send the finished packet (_gnutls_send_finished()),
and we expect the server change cipher spec packet 
( gnutls_recv_int(cd, state, GNUTLS_CHANGE_CIPHER_SPEC, NULL, 0)).

Then we receive the last message by calling _gnutls_recv_finished(cd, state),
and if everything was right, the connection was negotiated.

I know that this help may not be sufficient. Ask me if there is anything
else. (I should have updated doc/hacking)




DEBUG:

There are some debug flags in lib/gnutls_int.h
Use them at your option.

