From 1c74074782d3469deb301a5f09bda9b85ba16a9a Mon Sep 17 00:00:00 2001 From: Simon Josefsson Date: Thu, 6 Mar 2008 16:33:44 +0100 Subject: Doc fix. --- lib/gnutls_ui.c | 416 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 210 insertions(+), 206 deletions(-) diff --git a/lib/gnutls_ui.c b/lib/gnutls_ui.c index e90af7eae8..84046b09cb 100644 --- a/lib/gnutls_ui.c +++ b/lib/gnutls_ui.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation + * Copyright (C) 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -39,21 +39,19 @@ /* ANON & DHE */ /** - * gnutls_dh_set_prime_bits - Used to set the bits for a DH ciphersuite - * @session: is a #gnutls_session_t structure. - * @bits: is the number of bits - * - * This function sets the number of bits, for use in an - * Diffie Hellman key exchange. This is used both in DH ephemeral and - * DH anonymous cipher suites. This will set the - * minimum size of the prime that will be used for the handshake. - * - * In the client side it sets the minimum accepted number of bits. - * If a server sends a prime with less bits than that - * GNUTLS_E_DH_PRIME_UNACCEPTABLE will be returned by the - * handshake. - * - **/ + * gnutls_dh_set_prime_bits - Used to set the bits for a DH ciphersuite + * @session: is a #gnutls_session_t structure. + * @bits: is the number of bits + * + * This function sets the number of bits, for use in an Diffie Hellman + * key exchange. This is used both in DH ephemeral and DH anonymous + * cipher suites. This will set the minimum size of the prime that + * will be used for the handshake. + * + * In the client side it sets the minimum accepted number of bits. If + * a server sends a prime with less bits than that + * %GNUTLS_E_DH_PRIME_UNACCEPTABLE will be returned by the handshake. + **/ void gnutls_dh_set_prime_bits (gnutls_session_t session, unsigned int bits) { @@ -62,19 +60,20 @@ gnutls_dh_set_prime_bits (gnutls_session_t session, unsigned int bits) /** - * gnutls_dh_get_group - return the group of the DH authentication - * @session: is a gnutls session - * @raw_gen: will hold the generator. - * @raw_prime: will hold the prime. - * - * This function will return the group parameters used in the last Diffie Hellman - * authentication with the peer. These are the prime and the generator used. - * This function should be used for both anonymous and ephemeral diffie Hellman. - * The output parameters must be freed with gnutls_free(). - * - * Returns a negative value in case of an error. - * - **/ + * gnutls_dh_get_group - return the group of the DH authentication + * @session: is a gnutls session + * @raw_gen: will hold the generator. + * @raw_prime: will hold the prime. + * + * This function will return the group parameters used in the last + * Diffie Hellman authentication with the peer. These are the prime + * and the generator used. This function should be used for both + * anonymous and ephemeral diffie Hellman. The output parameters must + * be freed with gnutls_free(). + * + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise + * an error code is returned. + **/ int gnutls_dh_get_group (gnutls_session_t session, gnutls_datum_t * raw_gen, gnutls_datum_t * raw_prime) @@ -129,17 +128,18 @@ gnutls_dh_get_group (gnutls_session_t session, } /** - * gnutls_dh_get_pubkey - return the peer's public key used in DH authentication - * @session: is a gnutls session - * @raw_key: will hold the public key. - * - * This function will return the peer's public key used in the last Diffie Hellman authentication. - * This function should be used for both anonymous and ephemeral diffie Hellman. - * The output parameters must be freed with gnutls_free(). - * - * Returns a negative value in case of an error. - * - **/ + * gnutls_dh_get_pubkey - return the peer's public key used in DH authentication + * @session: is a gnutls session + * @raw_key: will hold the public key. + * + * This function will return the peer's public key used in the last + * Diffie Hellman authentication. This function should be used for + * both anonymous and ephemeral diffie Hellman. The output + * parameters must be freed with gnutls_free(). + * + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise + * an error code is returned. + **/ int gnutls_dh_get_pubkey (gnutls_session_t session, gnutls_datum_t * raw_key) { @@ -185,18 +185,18 @@ gnutls_dh_get_pubkey (gnutls_session_t session, gnutls_datum_t * raw_key) } /** - * gnutls_rsa_export_get_pubkey - return the peer's public key used in RSA-EXPORT authentication - * @session: is a gnutls session - * @exponent: will hold the exponent. - * @modulus: will hold the modulus. - * - * This function will return the peer's public key exponent and - * modulus used in the last RSA-EXPORT authentication. The output - * parameters must be freed with gnutls_free(). - * - * Returns a negative value in case of an error. - * - **/ + * gnutls_rsa_export_get_pubkey - return the peer's public key used in RSA-EXPORT authentication + * @session: is a gnutls session + * @exponent: will hold the exponent. + * @modulus: will hold the modulus. + * + * This function will return the peer's public key exponent and + * modulus used in the last RSA-EXPORT authentication. The output + * parameters must be freed with gnutls_free(). + * + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise + * an error code is returned. + **/ int gnutls_rsa_export_get_pubkey (gnutls_session_t session, gnutls_datum_t * exponent, @@ -236,14 +236,16 @@ gnutls_rsa_export_get_pubkey (gnutls_session_t session, /** - * gnutls_dh_get_secret_bits - return the bits used in DH authentication - * @session: is a gnutls session - * - * This function will return the bits used in the last Diffie Hellman authentication - * with the peer. Should be used for both anonymous and ephemeral diffie Hellman. - * Returns a negative value in case of an error. - * - **/ + * gnutls_dh_get_secret_bits - return the bits used in DH authentication + * @session: is a gnutls session + * + * This function will return the bits used in the last Diffie Hellman + * authentication with the peer. Should be used for both anonymous + * and ephemeral diffie Hellman. + * + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise + * an error code is returned. + **/ int gnutls_dh_get_secret_bits (gnutls_session_t session) { @@ -285,14 +287,16 @@ gnutls_dh_get_secret_bits (gnutls_session_t session) /** - * gnutls_dh_get_prime_bits - return the bits used in DH authentication - * @session: is a gnutls session - * - * This function will return the bits of the prime used in the last Diffie Hellman authentication - * with the peer. Should be used for both anonymous and ephemeral diffie Hellman. - * Returns a negative value in case of an error. - * - **/ + * gnutls_dh_get_prime_bits - return the bits used in DH authentication + * @session: is a gnutls session + * + * This function will return the bits of the prime used in the last + * Diffie Hellman authentication with the peer. Should be used for + * both anonymous and ephemeral diffie Hellman. + * + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise + * an error code is returned. + **/ int gnutls_dh_get_prime_bits (gnutls_session_t session) { @@ -341,14 +345,14 @@ gnutls_dh_get_prime_bits (gnutls_session_t session) } /** - * gnutls_rsa_export_get_modulus_bits - return the bits used in RSA-export key exchange - * @session: is a gnutls session - * - * This function will return the bits used in the last RSA-EXPORT key exchange - * with the peer. - * Returns a negative value in case of an error. - * - **/ + * gnutls_rsa_export_get_modulus_bits - return the bits used in RSA-export key exchange + * @session: is a gnutls session + * + * Get the export RSA parameter's modulus size. + * + * Returns: the bits used in the last RSA-EXPORT key exchange with the + * peer, or a negative value in case of error. + **/ int gnutls_rsa_export_get_modulus_bits (gnutls_session_t session) { @@ -362,14 +366,16 @@ gnutls_rsa_export_get_modulus_bits (gnutls_session_t session) } /** - * gnutls_dh_get_peers_public_bits - return the bits used in DH authentication - * @session: is a gnutls session - * - * This function will return the bits used in the last Diffie Hellman authentication - * with the peer. Should be used for both anonymous and ephemeral diffie Hellman. - * Returns a negative value in case of an error. - * - **/ + * gnutls_dh_get_peers_public_bits - return the bits used in DH authentication + * @session: is a gnutls session + * + * Get the Diffie-Hellman public key bit size. Can be used for both + * anonymous and ephemeral diffie Hellman. + * + * Returns: the public key bit size used in the last Diffie Hellman + * authentication with the peer, or a negative value in case of + * error. + **/ int gnutls_dh_get_peers_public_bits (gnutls_session_t session) { @@ -422,16 +428,17 @@ gnutls_dh_get_peers_public_bits (gnutls_session_t session) /* CERTIFICATE STUFF */ /** - * gnutls_certificate_get_ours - return the raw certificate sent in the last handshake - * @session: is a gnutls session - * - * This function will return the certificate as sent to the peer, - * in the last handshake. These certificates are in raw format. - * In X.509 this is a certificate list. In OpenPGP this is a single - * certificate. - * Returns NULL in case of an error, or if no certificate was used. - * - **/ + * gnutls_certificate_get_ours - return the raw certificate sent in the last handshake + * @session: is a gnutls session + * + * Get the certificate as sent to the peer, in the last handshake. + * These certificates are in raw format. In X.509 this is a + * certificate list. In OpenPGP this is a single certificate. + * + * Returns: return a pointer to a #gnutls_datum_t containing our + * certificates, or %NULL in case of an error or if no certificate + * was used. + **/ const gnutls_datum_t * gnutls_certificate_get_ours (gnutls_session_t session) { @@ -454,22 +461,23 @@ gnutls_certificate_get_ours (gnutls_session_t session) } /** - * gnutls_certificate_get_peers - return the peer's raw certificate - * @session: is a gnutls session - * @list_size: is the length of the certificate list - * - * This function will return the peer's raw certificate (chain) as - * sent by the peer. These certificates are in raw format (DER encoded - * for X.509). In case of a X.509 then a certificate list may be present. - * The first certificate in the list is the peer's certificate, - * following the issuer's certificate, then the issuer's issuer etc. - * - * In case of OpenPGP keys a single key will be returned - * in raw format. - * - * Returns NULL in case of an error, or if no certificate was sent. - * - **/ + * gnutls_certificate_get_peers - return the peer's raw certificate + * @session: is a gnutls session + * @list_size: is the length of the certificate list + * + * Get the peer's raw certificate (chain) as sent by the peer. These + * certificates are in raw format (DER encoded for X.509). In case of + * a X.509 then a certificate list may be present. The first + * certificate in the list is the peer's certificate, following the + * issuer's certificate, then the issuer's issuer etc. + * + * In case of OpenPGP keys a single key will be returned in raw + * format. + * + * Returns: return a pointer to a #gnutls_datum_t containing our + * certificates, or %NULL in case of an error or if no certificate + * was used. + **/ const gnutls_datum_t * gnutls_certificate_get_peers (gnutls_session_t session, unsigned int *list_size) @@ -488,14 +496,15 @@ gnutls_certificate_get_peers (gnutls_session_t /** - * gnutls_certificate_client_get_request_status - return the certificate request status - * @session: is a gnutls session - * - * This function will return 0 if the peer (server) did not request client - * authentication or 1 otherwise. - * Returns a negative value in case of an error. - * - **/ + * gnutls_certificate_client_get_request_status - return the certificate request status + * @session: is a gnutls session + * + * Get whether client certificate is requested or not. + * + * Returns: 0 if the peer (server) did not request client + * authentication or 1 otherwise, or a negative value in case of + * error. + **/ int gnutls_certificate_client_get_request_status (gnutls_session_t session) { @@ -510,25 +519,25 @@ gnutls_certificate_client_get_request_status (gnutls_session_t session) } /** - * gnutls_fingerprint - calculate the fingerprint of the given data - * @algo: is a digest algorithm - * @data: is the data - * @result: is the place where the result will be copied (may be null). - * @result_size: should hold the size of the result. The actual size - * of the returned result will also be copied there. - * - * This function will calculate a fingerprint (actually a hash), of the - * given data. The result is not printable data. You should convert it - * to hex, or to something else printable. - * - * This is the usual way to calculate a fingerprint of an X.509 - * DER encoded certificate. Note however that the fingerprint - * of an OpenPGP is not just a hash and cannot be calculated with - * this function. - * - * Returns a negative value in case of an error. - * - **/ + * gnutls_fingerprint - calculate the fingerprint of the given data + * @algo: is a digest algorithm + * @data: is the data + * @result: is the place where the result will be copied (may be null). + * @result_size: should hold the size of the result. The actual size + * of the returned result will also be copied there. + * + * This function will calculate a fingerprint (actually a hash), of + * the given data. The result is not printable data. You should + * convert it to hex, or to something else printable. + * + * This is the usual way to calculate a fingerprint of an X.509 DER + * encoded certificate. Note however that the fingerprint of an + * OpenPGP is not just a hash and cannot be calculated with this + * function. + * + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise + * an error code is returned. + **/ int gnutls_fingerprint (gnutls_digest_algorithm_t algo, const gnutls_datum_t * data, void *result, @@ -560,18 +569,18 @@ gnutls_fingerprint (gnutls_digest_algorithm_t algo, /** - * gnutls_certificate_set_dh_params - set the DH parameters for a server to use - * @res: is a gnutls_certificate_credentials_t structure - * @dh_params: is a structure that holds diffie hellman parameters. - * - * This function will set the diffie hellman parameters for a - * certificate server to use. These parameters will be used in - * Ephemeral Diffie Hellman cipher suites. Note that only a pointer - * to the parameters are stored in the certificate handle, so if you - * deallocate the parameters before the certificate is deallocated, - * you must change the parameters stored in the certificate first. - * - **/ + * gnutls_certificate_set_dh_params - set the DH parameters for a server to use + * @res: is a gnutls_certificate_credentials_t structure + * @dh_params: is a structure that holds diffie hellman parameters. + * + * This function will set the diffie hellman parameters for a + * certificate server to use. These parameters will be used in + * Ephemeral Diffie Hellman cipher suites. Note that only a pointer + * to the parameters are stored in the certificate handle, so if you + * deallocate the parameters before the certificate is deallocated, + * you must change the parameters stored in the certificate first. + * + **/ void gnutls_certificate_set_dh_params (gnutls_certificate_credentials_t res, gnutls_dh_params_t dh_params) @@ -580,15 +589,15 @@ gnutls_certificate_set_dh_params (gnutls_certificate_credentials_t res, } /** - * gnutls_certificate_set_params_function - set the DH or RSA parameters callback - * @res: is a gnutls_certificate_credentials_t structure - * @func: is the function to be called - * - * This function will set a callback in order for the server to get the - * diffie hellman or RSA parameters for certificate authentication. The callback - * should return zero on success. - * - **/ + * gnutls_certificate_set_params_function - set the DH or RSA parameters callback + * @res: is a gnutls_certificate_credentials_t structure + * @func: is the function to be called + * + * This function will set a callback in order for the server to get + * the diffie hellman or RSA parameters for certificate + * authentication. The callback should return zero on success. + * + **/ void gnutls_certificate_set_params_function (gnutls_certificate_credentials_t res, gnutls_params_function * func) @@ -598,15 +607,15 @@ gnutls_certificate_set_params_function (gnutls_certificate_credentials_t res, /** - * gnutls_certificate_set_verify_flags - set the flags to be used at certificate verification - * @res: is a gnutls_certificate_credentials_t structure - * @flags: are the flags - * - * This function will set the flags to be used at verification of the - * certificates. Flags must be OR of the - * #gnutls_certificate_verify_flags enumerations. - * - **/ + * gnutls_certificate_set_verify_flags - set the flags to be used at certificate verification + * @res: is a gnutls_certificate_credentials_t structure + * @flags: are the flags + * + * This function will set the flags to be used at verification of the + * certificates. Flags must be OR of the + * #gnutls_certificate_verify_flags enumerations. + * + **/ void gnutls_certificate_set_verify_flags (gnutls_certificate_credentials_t res, unsigned int flags) @@ -615,16 +624,16 @@ gnutls_certificate_set_verify_flags (gnutls_certificate_credentials_t } /** - * gnutls_certificate_set_verify_limits - set the upper limits to be used at certificate verification - * @res: is a gnutls_certificate_credentials structure - * @max_bits: is the number of bits of an acceptable certificate (default 8200) - * @max_depth: is maximum depth of the verification of a certificate chain (default 5) - * - * This function will set some upper limits for the default verification function, - * gnutls_certificate_verify_peers2(), to avoid denial of service attacks. - * You can set them to zero to disable limits. - * - **/ + * gnutls_certificate_set_verify_limits - set the upper limits to be used at certificate verification + * @res: is a gnutls_certificate_credentials structure + * @max_bits: is the number of bits of an acceptable certificate (default 8200) + * @max_depth: is maximum depth of the verification of a certificate chain (default 5) + * + * This function will set some upper limits for the default + * verification function, gnutls_certificate_verify_peers2(), to avoid + * denial of service attacks. You can set them to zero to disable + * limits. + **/ void gnutls_certificate_set_verify_limits (gnutls_certificate_credentials_t res, unsigned int max_bits, @@ -635,15 +644,14 @@ gnutls_certificate_set_verify_limits (gnutls_certificate_credentials_t } /** - * gnutls_certificate_set_rsa_export_params - set the RSA parameters for a server to use - * @res: is a gnutls_certificate_credentials_t structure - * @rsa_params: is a structure that holds temporary RSA parameters. - * - * This function will set the temporary RSA parameters for a certificate - * server to use. These parameters will be used in RSA-EXPORT - * cipher suites. - * - **/ + * gnutls_certificate_set_rsa_export_params - set the RSA parameters for a server to use + * @res: is a gnutls_certificate_credentials_t structure + * @rsa_params: is a structure that holds temporary RSA parameters. + * + * This function will set the temporary RSA parameters for a + * certificate server to use. These parameters will be used in + * RSA-EXPORT cipher suites. + **/ void gnutls_certificate_set_rsa_export_params (gnutls_certificate_credentials_t res, gnutls_rsa_params_t rsa_params) @@ -652,15 +660,14 @@ gnutls_certificate_set_rsa_export_params (gnutls_certificate_credentials_t } /** - * gnutls_psk_set_params_function - set the DH or RSA parameters callback - * @res: is a gnutls_psk_server_credentials_t structure - * @func: is the function to be called - * - * This function will set a callback in order for the server to get the - * diffie hellman or RSA parameters for psk authentication. The callback - * should return zero on success. - * - **/ + * gnutls_psk_set_params_function - set the DH or RSA parameters callback + * @res: is a gnutls_psk_server_credentials_t structure + * @func: is the function to be called + * + * This function will set a callback in order for the server to get + * the diffie hellman or RSA parameters for psk authentication. The + * callback should return zero on success. + **/ void gnutls_psk_set_params_function (gnutls_psk_server_credentials_t res, gnutls_params_function * func) @@ -668,18 +675,15 @@ gnutls_psk_set_params_function (gnutls_psk_server_credentials_t res, res->params_func = func; } - - /** - * gnutls_anon_set_params_function - set the DH or RSA parameters callback - * @res: is a gnutls_anon_server_credentials_t structure - * @func: is the function to be called - * - * This function will set a callback in order for the server to get the - * diffie hellman or RSA parameters for anonymous authentication. The callback - * should return zero on success. - * - **/ + * gnutls_anon_set_params_function - set the DH or RSA parameters callback + * @res: is a gnutls_anon_server_credentials_t structure + * @func: is the function to be called + * + * This function will set a callback in order for the server to get + * the diffie hellman or RSA parameters for anonymous authentication. + * The callback should return zero on success. + **/ void gnutls_anon_set_params_function (gnutls_anon_server_credentials_t res, gnutls_params_function * func) -- cgit v1.2.1