diff options
author | Simon Josefsson <simon@josefsson.org> | 2008-03-06 16:48:22 +0100 |
---|---|---|
committer | Simon Josefsson <simon@josefsson.org> | 2008-03-06 16:48:22 +0100 |
commit | 48f0074bfa60571d89007f879133456c2302e936 (patch) | |
tree | c6627061e592c3cbfb7d7992a2436a886a5a0868 | |
parent | 1c74074782d3469deb301a5f09bda9b85ba16a9a (diff) | |
download | gnutls-48f0074bfa60571d89007f879133456c2302e936.tar.gz |
Doc fixes.
-rw-r--r-- | lib/gnutls_alert.c | 31 | ||||
-rw-r--r-- | lib/gnutls_algorithms.c | 186 | ||||
-rw-r--r-- | lib/gnutls_record.c | 14 | ||||
-rw-r--r-- | lib/gnutls_state.c | 196 |
4 files changed, 231 insertions, 196 deletions
diff --git a/lib/gnutls_alert.c b/lib/gnutls_alert.c index 200023482d..ce448b65d3 100644 --- a/lib/gnutls_alert.c +++ b/lib/gnutls_alert.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation + * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -137,20 +137,21 @@ gnutls_alert_send (gnutls_session_t session, gnutls_alert_level_t level, } /** - * gnutls_error_to_alert - return an alert code based on the given error code - * @err: is a negative integer - * @level: the alert level will be stored there - * - * Returns an alert depending on the error code returned by a gnutls - * function. All alerts sent by this function should be considered fatal. - * The only exception is when err == GNUTLS_E_REHANDSHAKE, where a warning - * alert should be sent to the peer indicating that no renegotiation will - * be performed. - * - * If there is no mapping to a valid alert the alert to indicate internal error - * is returned. - * - **/ + * gnutls_error_to_alert - return an alert code based on the given error code + * @err: is a negative integer + * @level: the alert level will be stored there + * + * Get an alert depending on the error code returned by a gnutls + * function. All alerts sent by this function should be considered + * fatal. The only exception is when @err is %GNUTLS_E_REHANDSHAKE, + * where a warning alert should be sent to the peer indicating that no + * renegotiation will be performed. + * + * If there is no mapping to a valid alert the alert to indicate + * internal error is returned. + * + * Returns: the alert code to use for a particular error code. + **/ int gnutls_error_to_alert (int err, int *level) { diff --git a/lib/gnutls_algorithms.c b/lib/gnutls_algorithms.c index 8866a18da0..39de351c06 100644 --- a/lib/gnutls_algorithms.c +++ b/lib/gnutls_algorithms.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2000, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation + * Copyright (C) 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -667,12 +667,14 @@ _gnutls_mac_priority (gnutls_session_t session, } /** - * gnutls_mac_get_name - Returns a string with the name of the specified mac algorithm - * @algorithm: is a MAC algorithm - * - * Returns: a string that contains the name of the specified MAC - * algorithm, or %NULL. - **/ + * gnutls_mac_get_name - Returns a string with the name of the specified mac algorithm + * @algorithm: is a MAC algorithm + * + * Convert a #gnutls_mac_algorithm_t value to a string. + * + * Returns: a string that contains the name of the specified MAC + * algorithm, or %NULL. + **/ const char * gnutls_mac_get_name (gnutls_mac_algorithm_t algorithm) { @@ -685,13 +687,15 @@ gnutls_mac_get_name (gnutls_mac_algorithm_t algorithm) } /** - * gnutls_mac_get_id - Returns the gnutls id of the specified in string algorithm - * @algorithm: is a MAC algorithm name - * - * Returns: an %gnutls_mac_algorithm_tid of the specified in a string - * MAC algorithm, or %GNUTLS_MAC_UNKNOWN on failures. The names are - * compared in a case insensitive way. - **/ + * gnutls_mac_get_id - Returns the gnutls id of the specified in string algorithm + * @algorithm: is a MAC algorithm name + * + * Convert a string to a #gnutls_mac_algorithm_t value. The names are + * compared in a case insensitive way. + * + * Returns: an %gnutls_mac_algorithm_tid of the specified in a string + * MAC algorithm, or %GNUTLS_MAC_UNKNOWN on failures. + **/ gnutls_mac_algorithm_t gnutls_mac_get_id (const char* name) { @@ -703,13 +707,14 @@ gnutls_mac_get_id (const char* name) } /** - * gnutls_mac_get_key_size - Returns the length of the MAC's key size - * @algorithm: is an encryption algorithm - * - * Returns: length (in bytes) of the given MAC key size, or 0 if the - * given MAC algorithm is invalid. - * - **/ + * gnutls_mac_get_key_size - Returns the length of the MAC's key size + * @algorithm: is an encryption algorithm + * + * Get size of MAC key. + * + * Returns: length (in bytes) of the given MAC key size, or 0 if the + * given MAC algorithm is invalid. + **/ size_t gnutls_mac_get_key_size (gnutls_mac_algorithm_t algorithm) { @@ -794,12 +799,14 @@ _gnutls_compression_priority (gnutls_session_t session, } /** - * gnutls_compression_get_name - Returns a string with the name of the specified compression algorithm - * @algorithm: is a Compression algorithm - * - * Returns: a pointer to a string that contains the name of the - * specified compression algorithm, or %NULL. - **/ + * gnutls_compression_get_name - Returns a string with the name of the specified compression algorithm + * @algorithm: is a Compression algorithm + * + * Convert a #gnutls_compression_method_t value to a string. + * + * Returns: a pointer to a string that contains the name of the + * specified compression algorithm, or %NULL. + **/ const char * gnutls_compression_get_name (gnutls_compression_method_t algorithm) { @@ -812,15 +819,14 @@ gnutls_compression_get_name (gnutls_compression_method_t algorithm) } /** - * gnutls_compression_get_id - Returns the gnutls id of the specified in string algorithm - * @algorithm: is a compression method name - * - * The names are compared in a case insensitive way. - * - * Returns: an id of the specified in a string compression method, or - * %GNUTLS_COMP_UNKNOWN on error. - * - **/ + * gnutls_compression_get_id - Returns the gnutls id of the specified in string algorithm + * @algorithm: is a compression method name + * + * The names are compared in a case insensitive way. + * + * Returns: an id of the specified in a string compression method, or + * %GNUTLS_COMP_UNKNOWN on error. + **/ gnutls_compression_method_t gnutls_compression_get_id (const char* name) { @@ -952,12 +958,14 @@ _gnutls_cipher_is_block (gnutls_cipher_algorithm_t algorithm) } /** - * gnutls_cipher_get_key_size - Returns the length of the cipher's key size - * @algorithm: is an encryption algorithm - * - * Returns: length (in bytes) of the given cipher's key size, o 0 if - * the given cipher is invalid. - **/ + * gnutls_cipher_get_key_size - Returns the length of the cipher's key size + * @algorithm: is an encryption algorithm + * + * Get key size for cipher. + * + * Returns: length (in bytes) of the given cipher's key size, or 0 if + * the given cipher is invalid. + **/ size_t gnutls_cipher_get_key_size (gnutls_cipher_algorithm_t algorithm) { /* In bytes */ @@ -986,12 +994,14 @@ _gnutls_cipher_get_export_flag (gnutls_cipher_algorithm_t algorithm) } /** - * gnutls_cipher_get_name - Returns a string with the name of the specified cipher algorithm - * @algorithm: is an encryption algorithm - * - * Returns: a pointer to a string that contains the name of the - * specified cipher, or %NULL. - **/ + * gnutls_cipher_get_name - Returns a string with the name of the specified cipher algorithm + * @algorithm: is an encryption algorithm + * + * Convert a #gnutls_cipher_algorithm_t type to a string. + * + * Returns: a pointer to a string that contains the name of the + * specified cipher, or %NULL. + **/ const char * gnutls_cipher_get_name (gnutls_cipher_algorithm_t algorithm) { @@ -1004,15 +1014,14 @@ gnutls_cipher_get_name (gnutls_cipher_algorithm_t algorithm) } /** - * gnutls_cipher_get_id - Returns the gnutls id of the specified in string algorithm - * @algorithm: is a MAC algorithm name - * - * The names are compared in a case insensitive way. - * - * Returns: an id of the specified cipher, or %GNUTLS_CIPHER_UNKNOWN - * on error. - * - **/ + * gnutls_cipher_get_id - Returns the gnutls id of the specified in string algorithm + * @algorithm: is a MAC algorithm name + * + * The names are compared in a case insensitive way. + * + * Returns: return a #gnutls_cipher_algorithm_t value corresponding to + * the specified cipher, or %GNUTLS_CIPHER_UNKNOWN on error. + **/ gnutls_cipher_algorithm_t gnutls_cipher_get_id (const char* name) { @@ -1078,12 +1087,14 @@ _gnutls_kx_priority (gnutls_session_t session, } /** - * gnutls_kx_get_name - Returns a string with the name of the specified key exchange algorithm - * @algorithm: is a key exchange algorithm - * - * Returns: a pointer to a string that contains the name of the - * specified key exchange algorithm, or %NULL. - **/ + * gnutls_kx_get_name - Returns a string with the name of the specified key exchange algorithm + * @algorithm: is a key exchange algorithm + * + * Convert a #gnutls_kx_algorithm_t value to a string. + * + * Returns: a pointer to a string that contains the name of the + * specified key exchange algorithm, or %NULL. + **/ const char * gnutls_kx_get_name (gnutls_kx_algorithm_t algorithm) { @@ -1096,14 +1107,15 @@ gnutls_kx_get_name (gnutls_kx_algorithm_t algorithm) } /** - * gnutls_kx_get_id - Returns the gnutls id of the specified in string algorithm - * @algorithm: is a KX name - * - * The names are compared in a case insensitive way. - * - * Returns: an id of the specified KX algorithm, or - * %GNUTLS_KX_UNKNOWN on error. - **/ + * gnutls_kx_get_id - Returns the gnutls id of the specified in string algorithm + * @algorithm: is a KX name + * + * Convert a string to a #gnutls_kx_algorithm_t value. The names are + * compared in a case insensitive way. + * + * Returns: an id of the specified KX algorithm, or %GNUTLS_KX_UNKNOWN + * on error. + **/ gnutls_kx_algorithm_t gnutls_kx_get_id (const char* name) { @@ -1223,12 +1235,14 @@ _gnutls_version_max (gnutls_session_t session) /** - * gnutls_protocol_get_name - Returns a string with the name of the specified SSL/TLS version - * @version: is a (gnutls) version number - * - * Returns: a string that contains the name of the specified TLS - * version (e.g., "TLS 1.0"), or %NULL. - **/ + * gnutls_protocol_get_name - Returns a string with the name of the specified SSL/TLS version + * @version: is a (gnutls) version number + * + * Convert a #gnutls_protocol_t value to a string. + * + * Returns: a string that contains the name of the specified TLS + * version (e.g., "TLS1.0"), or %NULL. + **/ const char * gnutls_protocol_get_name (gnutls_protocol_t version) { @@ -1815,12 +1829,14 @@ _gnutls_supported_compression_methods (gnutls_session_t session, } /** - * gnutls_certificate_type_get_name - Returns a string with the name of the specified certificate type - * @type: is a certificate type - * - * Returns: a string (or %NULL) that contains the name of the - * specified certificate type. - **/ + * gnutls_certificate_type_get_name - Returns a string with the name of the specified certificate type + * @type: is a certificate type + * + * Convert a #gnutls_certificate_type_t type to a string. + * + * Returns: a string that contains the name of the specified + * certificate type, or %NULL in case of unknown types. + **/ const char * gnutls_certificate_type_get_name (gnutls_certificate_type_t type) { @@ -2037,8 +2053,10 @@ static const gnutls_pk_entry pk_algorithms[] = { * gnutls_pk_algorithm_get_name - Returns a string with the name of the specified public key algorithm * @algorithm: is a pk algorithm * + * Convert a #gnutls_pk_algorithm_t value to a string. + * * Returns: a string that contains the name of the specified public - * key algorithm, or %NULL. + * key algorithm, or %NULL. **/ const char * gnutls_pk_algorithm_get_name (gnutls_pk_algorithm_t algorithm) diff --git a/lib/gnutls_record.c b/lib/gnutls_record.c index 72b9ac30b4..ca4aea7420 100644 --- a/lib/gnutls_record.c +++ b/lib/gnutls_record.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation + * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -45,11 +45,13 @@ #include <gnutls_dh.h> /** - * gnutls_protocol_get_version - Returns the version of the currently used protocol - * @session: is a #gnutls_session_t structure. - * - * Returns: the version of the currently used protocol. - **/ + * gnutls_protocol_get_version - Returns the version of the currently used protocol + * @session: is a #gnutls_session_t structure. + * + * Get TLS version, a #gnutls_protocol_t value. + * + * Returns: the version of the currently used protocol. + **/ gnutls_protocol_t gnutls_protocol_get_version (gnutls_session_t session) { diff --git a/lib/gnutls_state.c b/lib/gnutls_state.c index ab36e3bdb2..3d91ca641a 100644 --- a/lib/gnutls_state.c +++ b/lib/gnutls_state.c @@ -52,11 +52,14 @@ _gnutls_session_cert_type_set (gnutls_session_t session, } /** - * gnutls_cipher_get - Returns the currently used cipher. - * @session: is a #gnutls_session_t structure. - * - * Returns: the currently used cipher. - **/ + * gnutls_cipher_get - Returns the currently used cipher. + * @session: is a #gnutls_session_t structure. + * + * Get currently used cipher. + * + * Returns: the currently used cipher, an #gnutls_cipher_algorithm_t + * type. + **/ gnutls_cipher_algorithm_t gnutls_cipher_get (gnutls_session_t session) { @@ -64,15 +67,15 @@ gnutls_cipher_get (gnutls_session_t session) } /** - * gnutls_certificate_type_get - Returns the currently used certificate type. - * @session: is a #gnutls_session_t structure. - * - * The certificate type is by default X.509, unless it is negotiated - * as a TLS extension. - * - * Returns: the currently used %gnutls_certificate_type_t certificate - * type. - **/ + * gnutls_certificate_type_get - Returns the currently used certificate type. + * @session: is a #gnutls_session_t structure. + * + * The certificate type is by default X.509, unless it is negotiated + * as a TLS extension. + * + * Returns: the currently used #gnutls_certificate_type_t certificate + * type. + **/ gnutls_certificate_type_t gnutls_certificate_type_get (gnutls_session_t session) { @@ -80,11 +83,14 @@ gnutls_certificate_type_get (gnutls_session_t session) } /** - * gnutls_kx_get - Returns the key exchange algorithm. - * @session: is a #gnutls_session_t structure. - * - * Returns: the key exchange algorithm used in the last handshake. - **/ + * gnutls_kx_get - Returns the key exchange algorithm. + * @session: is a #gnutls_session_t structure. + * + * Get currently used key exchange algorithm. + * + * Returns: the key exchange algorithm used in the last handshake, a + * #gnutls_kx_algorithm_t value. + **/ gnutls_kx_algorithm_t gnutls_kx_get (gnutls_session_t session) { @@ -92,11 +98,14 @@ gnutls_kx_get (gnutls_session_t session) } /** - * gnutls_mac_get - Returns the currently used mac algorithm. - * @session: is a #gnutls_session_t structure. - * - * Returns: the currently used mac algorithm. - **/ + * gnutls_mac_get - Returns the currently used mac algorithm. + * @session: is a #gnutls_session_t structure. + * + * Get currently used MAC algorithm. + * + * Returns: the currently used mac algorithm, a + * #gnutls_mac_algorithm_t value. + **/ gnutls_mac_algorithm_t gnutls_mac_get (gnutls_session_t session) { @@ -104,11 +113,14 @@ gnutls_mac_get (gnutls_session_t session) } /** - * gnutls_compression_get - Returns the currently used compression algorithm. - * @session: is a #gnutls_session_t structure. - * - * Returns: the currently used compression method. - **/ + * gnutls_compression_get - Returns the currently used compression algorithm. + * @session: is a #gnutls_session_t structure. + * + * Get currently used compression algorithm. + * + * Returns: the currently used compression method, a + * #gnutls_compression_method_t value. + **/ gnutls_compression_method_t gnutls_compression_get (gnutls_session_t session) { @@ -1140,12 +1152,15 @@ _gnutls_session_is_export (gnutls_session_t session) } /** - * gnutls_session_get_ptr - Used to get the user pointer from the session structure - * @session: is a #gnutls_session_t structure. - * - * Returns: the user given pointer from the session structure. This - * is the pointer set with gnutls_session_set_ptr(). - **/ + * gnutls_session_get_ptr - Get the user pointer from the session structure + * @session: is a #gnutls_session_t structure. + * + * Get user pointer for session. Useful in callbacks. This is the + * pointer set with gnutls_session_set_ptr(). + * + * Returns: the user given pointer from the session structure, or + * %NULL if it was never set. + **/ void * gnutls_session_get_ptr (gnutls_session_t session) { @@ -1153,14 +1168,14 @@ gnutls_session_get_ptr (gnutls_session_t session) } /** - * gnutls_session_set_ptr - Used to set the user pointer to the session structure - * @session: is a #gnutls_session_t structure. - * @ptr: is the user pointer - * - * This function will set (associate) the user given pointer to the - * session structure. This is pointer can be accessed with - * gnutls_session_get_ptr(). - **/ + * gnutls_session_set_ptr - Used to set the user pointer to the session structure + * @session: is a #gnutls_session_t structure. + * @ptr: is the user pointer + * + * This function will set (associate) the user given pointer @ptr to + * the session structure. This is pointer can be accessed with + * gnutls_session_get_ptr(). + **/ void gnutls_session_set_ptr (gnutls_session_t session, void *ptr) { @@ -1169,22 +1184,22 @@ gnutls_session_set_ptr (gnutls_session_t session, void *ptr) /** - * gnutls_record_get_direction - return the direction of the last interrupted function call - * @session: is a #gnutls_session_t structure. - * - * This function provides information about the internals of the - * record protocol and is only useful if a prior gnutls function call - * (e.g. gnutls_handshake()) was interrupted for some reason, that - * is, if a function returned %GNUTLS_E_INTERRUPTED or - * %GNUTLS_E_AGAIN. In such a case, you might want to call select() - * or poll() before calling the interrupted gnutls function again. - * To tell you whether a file descriptor should be selected for - * either reading or writing, gnutls_record_get_direction() returns 0 - * if the interrupted function was trying to read data, and 1 if it - * was trying to write data. - * - * Returns: 0 if trying to read data, 1 if trying to write data. - **/ + * gnutls_record_get_direction - return the direction of the last interrupted function call + * @session: is a #gnutls_session_t structure. + * + * This function provides information about the internals of the + * record protocol and is only useful if a prior gnutls function call + * (e.g. gnutls_handshake()) was interrupted for some reason, that + * is, if a function returned %GNUTLS_E_INTERRUPTED or + * %GNUTLS_E_AGAIN. In such a case, you might want to call select() + * or poll() before calling the interrupted gnutls function again. To + * tell you whether a file descriptor should be selected for either + * reading or writing, gnutls_record_get_direction() returns 0 if the + * interrupted function was trying to read data, and 1 if it was + * trying to write data. + * + * Returns: 0 if trying to read data, 1 if trying to write data. + **/ int gnutls_record_get_direction (gnutls_session_t session) { @@ -1211,27 +1226,26 @@ _gnutls_rsa_pms_set_version (gnutls_session_t session, } /** - * gnutls_handshake_set_post_client_hello_function - set callback to be called after the client hello is received - * @res: is a gnutls_anon_server_credentials_t structure - * @func: is the function to be called - * - * This function will set a callback to be called after the client - * hello has been received (callback valid in server side only). This - * allows the server to adjust settings based on received extensions. - * - * Those settings could be ciphersuites, requesting certificate, or - * anything else except for version negotiation (this is done before - * the hello message is parsed). - * - * This callback must return 0 on success or a gnutls error code to - * terminate the handshake. - * - * NOTE: You should not use this function to terminate the handshake - * based on client input unless you know what you are doing. Before - * the handshake is finished there is no way to know if there is a - * man-in-the-middle attack being performed. - * - **/ + * gnutls_handshake_set_post_client_hello_function - set callback to be called after the client hello is received + * @res: is a gnutls_anon_server_credentials_t structure + * @func: is the function to be called + * + * This function will set a callback to be called after the client + * hello has been received (callback valid in server side only). This + * allows the server to adjust settings based on received extensions. + * + * Those settings could be ciphersuites, requesting certificate, or + * anything else except for version negotiation (this is done before + * the hello message is parsed). + * + * This callback must return 0 on success or a gnutls error code to + * terminate the handshake. + * + * NOTE: You should not use this function to terminate the handshake + * based on client input unless you know what you are doing. Before + * the handshake is finished there is no way to know if there is a + * man-in-the-middle attack being performed. + **/ void gnutls_handshake_set_post_client_hello_function (gnutls_session_t session, gnutls_handshake_post_client_hello_func func) @@ -1240,17 +1254,17 @@ gnutls_handshake_set_post_client_hello_function (gnutls_session_t session, } /** - * gnutls_session_enable_compatibility_mode - Used to disable certain features in TLS in order to honour compatibility - * @session: is a #gnutls_session_t structure. - * - * This function can be used to disable certain (security) features - * in TLS in order to maintain maximum compatibility with buggy - * clients. It is equivalent to calling: - * gnutls_record_disable_padding() - * - * Normally only servers that require maximum compatibility with - * everything out there, need to call this function. - **/ + * gnutls_session_enable_compatibility_mode - disable certain features in TLS in order to honour compatibility + * @session: is a #gnutls_session_t structure. + * + * This function can be used to disable certain (security) features in + * TLS in order to maintain maximum compatibility with buggy + * clients. It is equivalent to calling: + * gnutls_record_disable_padding() + * + * Normally only servers that require maximum compatibility with + * everything out there, need to call this function. + **/ void gnutls_session_enable_compatibility_mode (gnutls_session_t session) { |