From a0daa68d18a08e197cfb1f3e85442e958ac4192d Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Wed, 30 May 2001 11:23:23 +0000 Subject: updated API and documentation. Now we use the gnome way for creating API docs. --- doc/API | 194 -------------------------------------------------------- doc/Makefile.am | 11 +++- doc/TODO | 1 - 3 files changed, 10 insertions(+), 196 deletions(-) delete mode 100644 doc/API (limited to 'doc') diff --git a/doc/API b/doc/API deleted file mode 100644 index ff1ddd76c5..0000000000 --- a/doc/API +++ /dev/null @@ -1,194 +0,0 @@ -This may not be complete yet. Check at gnutls.h for current information. - -All functions return >=0 if everything is ok, or a negative value in case -of a failure. Failure is not always fatal. - -int gnutls_init(GNUTLS_STATE * state, ConnectionEnd con_end); - This function just initializes a gnutls state to null. - con_end can be either GNUTLS_CLIENT or GNUTLS_SERVER. - -int gnutls_deinit(GNUTLS_STATE state); - This function clears all buffers associated with the state. - -int gnutls_handshake(int cd, GNUTLS_STATE state); - This function does the handshake of the TLS/SSL protocol, - and initializes the TLS connection. - It accepts a TCP connection descriptor and a GNUTLS state. - This function will fail if any problem is encountered, - and the connection should be terminated. - -int gnutls_handshake_begin(int cd, GNUTLS_STATE state); - This function does the handshake of the TLS/SSL protocol. - This function will fail if any problem is encountered. - However this failure will not be fatal. You may choose to - continue the handshake - eg. even if the certificate cannot - be verified- by calling gnutls_handshake_finish() - -int gnutls_handshake_finish(int cd, GNUTLS_STATE state); - This function does the final stuff of the handshake protocol. - This function will fail if any problem is encountered. - -int gnutls_close(int cd, GNUTLS_STATE state); - Terminates the current TLS/SSL connection. If it returns 0 - you may continue using the TCP connection. - -int gnutls_send_hello_request(int cd, GNUTLS_STATE state); - 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. - -AlertDescription gnutls_get_last_alert( GNUTLS_STATE state); - 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. - -KXAlgorithm gnutls_get_current_kx( GNUTLS_STATE state); - Returns the key exchange algorithm used in the first key exchange. - (There is not key exchange in resumed sessions). - -BulkCipherAlgorithm gnutls_get_current_cipher( GNUTLS_STATE state); - Returns the currently used cipher. - -char *_gnutls_cipher_get_name(BulkCipherAlgorithm); - Returns a malloc'ed string with the name of the algorithm; - -MACAlgorithm gnutls_get_current_mac_algorithm( GNUTLS_STATE state); - Returns the mac algorithm used. - -char *_gnutls_mac_get_name(MACAlgorithm); - Returns a malloc'ed string with the name of the algorithm; - -CompressionMethod gnutls_get_current_compression_method( GNUTLS_STATE state); - Returns the compression algorithm used. - -char *_gnutls_compression_get_name(CompressionMethod); - Returns a malloc'ed string with the name of the algorithm; - -int gnutls_is_fatal_error( int error); - 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 manual, since some non-fatal errors to the protocol - may be fatal for you (your program). - -void gnutls_perror( int error); -char* gnutls_strerror( int error); - These funtions are like perror() and strerror(). - gnutls_strerror() returns a malloc'ed value thus it must be - freed. - -ssize_t gnutls_write(int cd, GNUTLS_STATE state, void* data, int sizeofdata); - This function has the same semantics as write() has. The only - difference is that is accepts a GNUTLS state. - -ssize_t gnutls_read(int cd, GNUTLS_STATE state, void* data, int sizeofdata); - This function has the same semantics as read() has. The only - difference is that is accepts a GNUTLS state. - -ssize_t gnutls_recv(int cd, GNUTLS_STATE state, void* data, int sizeofdata, int flags); - 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. - -ssize_t gnutls_send(int cd, GNUTLS_STATE state, void* data, int sizeofdata, int flags); - 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. - -int gnutls_check_pending( GNUTLS_STATE state); - 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). - -void gnutls_set_cipher_priority( GNUTLS_STATE state, ...); - 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. - -int gnutls_set_kx_cred( GNUTLS_STATE state, int kx, void* cred); - 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. - -void* gnutls_get_auth_info( GNUTLS_STATE state); - Must be called after a complete gnutls_handshake(). - Returns a pointer to authentication information. - * For GNUTLS_KX_ANON returns a pointer to DH_ANON_AUTH_INFO; - * For GNUTLS_KX_SRP returns a pointer to structure SRP_AUTH_INFO. - (you should not free that). Thus you can access the - username he used to connect. - -void gnutls_set_kx_priority( GNUTLS_STATE state, ...); - like gnutls_set_cipher_priority, but for key exchange methods. - -void gnutls_set_mac_priority( GNUTLS_STATE state, ...); - like gnutls_set_cipher_priority, but for mac algorithms. - -void gnutls_set_compression_priority( GNUTLS_STATE state, ...); - like gnutls_set_cipher_priority, but for compression algorithms. - -void gnutls_set_current_version(GNUTLS_STATE state, GNUTLS_Version version); - Sets the current SSL/TLS version. Accepted values are GNUTLS_SSL3 - and GNUTLS_TLS1. - -int gnutls_get_current_session_id( GNUTLS_STATE state, void* session, int *session_size); - Returns the 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) - -int gnutls_get_current_session( GNUTLS_STATE state, void* session, int *session_size); - Returns all session parameters - in order to support resuming. - The client should call this - and keep the returned session - if he wants to - resume that current version later by calling gnutls_set_current_session(). - This function must be called after a successful handshake. - -int gnutls_set_current_session( GNUTLS_STATE state, void* session, int session_size); - Sets all session parameters - in order to support resuming - session must be the one returned by get_current_session(); - This function should be called before gnutls_handshake_begin. - Keep in mind that session resuming is advisory. The server may - choose not to resume the session, thus a full handshake will be - performed. - -int gnutls_set_lowat( GNUTLS_STATE state, int num); - 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. - -int gnutls_set_cache_expiration( GNUTLS_STATE state, int seconds); - Sets the expiration time for resumed sessions. - -int gnutls_set_db_name( GNUTLS_STATE state, char* filename); - Sets the name of the (gdbm) database to be used to keep - the sessions to be resumed. - -int gnutls_clean_db( GNUTLS_STATE state); - Deletes all expired records in the db. This db may become huge - if this is not called. diff --git a/doc/Makefile.am b/doc/Makefile.am index 0aae5e3186..9840929f62 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1 +1,10 @@ -EXTRA_DIST = TODO API +EXTRA_DIST = TODO gnutls.3 gnutls-api.txt gnutls-api.html +man_MANS = gnutls.3 + +gnutls.3: + @gdoc -man ../lib/*.c > gnutls.3 +gnutls-api: gnutls-api.html gnutls-api.txt +gnutls-api.html: + @gdoc -man ../lib/*.c > gnutls-api.html +gnutls-api.txt: + @gdoc -text ../lib/*.c > gnutls-api.txt diff --git a/doc/TODO b/doc/TODO index ae8b335918..638cff1880 100644 --- a/doc/TODO +++ b/doc/TODO @@ -1,5 +1,4 @@ * x509 Certificate API ( Fabio.Fiorina@alcatel.it is currently working on an ASN.1 parser) * OpenPGP certificate support (through libgcrypt) -* Document API using texi (any volunteers?) * Add Kerberos support (who wants that?) * Audit the code (volunteers?) -- cgit v1.2.1