From a39c5f9fafd4b7bb4396b7a90c2cd66af3fa4290 Mon Sep 17 00:00:00 2001 From: Simon Josefsson Date: Wed, 13 May 2009 17:51:30 +0200 Subject: Doc fixes for GTK-DOC. --- lib/gnutls_algorithms.c | 24 +++++----- lib/gnutls_auth.c | 55 ++++++++++++----------- lib/gnutls_buffers.c | 24 +++++----- lib/gnutls_cert.c | 11 +++-- lib/gnutls_global.c | 6 +-- lib/gnutls_priority.c | 3 +- lib/gnutls_psk.c | 18 ++++---- lib/gnutls_session.c | 35 ++++++++------- lib/gnutls_state.c | 11 +++-- lib/includes/gnutls/gnutls.h.in | 57 ++++++++++++------------ lib/includes/gnutls/openpgp.h | 15 ++++--- lib/includes/gnutls/pkcs12.h | 7 +-- lib/includes/gnutls/x509.h | 9 ++-- lib/openpgp/extras.c | 6 +-- lib/openpgp/gnutls_openpgp.c | 98 +++++++++++++++++++++-------------------- lib/openpgp/pgp.c | 6 ++- lib/openpgp/privkey.c | 6 +-- lib/x509/crq.c | 1 + lib/x509/dn.c | 1 - lib/x509/pkcs12_bag.c | 67 +++++++++++++++------------- lib/x509/x509.c | 35 ++++++++------- lib/x509/x509_write.c | 6 ++- libextra/gnutls_ia.c | 9 ++-- 23 files changed, 268 insertions(+), 242 deletions(-) diff --git a/lib/gnutls_algorithms.c b/lib/gnutls_algorithms.c index a8929edbf4..e45f4c1484 100644 --- a/lib/gnutls_algorithms.c +++ b/lib/gnutls_algorithms.c @@ -1262,17 +1262,17 @@ _gnutls_cipher_suite_get_name (cipher_suite_st * suite) } /** - * gnutls_cipher_suite_get_name - Returns a string with the name of the specified cipher suite - * @kx_algorithm: is a Key exchange algorithm - * @cipher_algorithm: is a cipher algorithm - * @mac_algorithm: is a MAC algorithm - * - * Note that the full cipher suite name must be prepended by TLS or - * SSL depending of the protocol in use. - * - * Returns: a string that contains the name of a TLS cipher suite, - * specified by the given algorithms, or %NULL. - **/ + * gnutls_cipher_suite_get_name - get name of the specified cipher suite + * @kx_algorithm: is a Key exchange algorithm + * @cipher_algorithm: is a cipher algorithm + * @mac_algorithm: is a MAC algorithm + * + * Note that the full cipher suite name must be prepended by TLS or + * SSL depending of the protocol in use. + * + * Returns: a string that contains the name of a TLS cipher suite, + * specified by the given algorithms, or %NULL. + **/ const char * gnutls_cipher_suite_get_name (gnutls_kx_algorithm_t kx_algorithm, gnutls_cipher_algorithm_t cipher_algorithm, @@ -1775,7 +1775,7 @@ static const gnutls_sign_algorithm_t supported_sign[] = { /** * gnutls_sign_algorithm_get_name - Returns a string with the name of the specified sign algorithm - * @algorithm: is a sign algorithm + * @sign: is a sign algorithm * * Convert a #gnutls_sign_algorithm_t value to a string. * diff --git a/lib/gnutls_auth.c b/lib/gnutls_auth.c index 77af880807..ba15a483ae 100644 --- a/lib/gnutls_auth.c +++ b/lib/gnutls_auth.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation + * Copyright (C) 2001, 2002, 2003, 2004, 2005, 2008, 2009 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -66,30 +66,35 @@ gnutls_credentials_clear (gnutls_session_t session) * { algorithm, credentials, pointer to next } */ /** - * gnutls_credentials_set - Sets the needed credentials for the specified authentication algorithm. - * @session: is a #gnutls_session_t structure. - * @type: is the type of the credentials - * @cred: is a pointer to a structure. - * - * 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 session (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_CRD_ANON cred should be gnutls_anon_client_credentials_t in case of a client. - * In case of a server it should be gnutls_anon_server_credentials_t. - * - * For GNUTLS_CRD_SRP cred should be gnutls_srp_client_credentials_t - * in case of a client, and gnutls_srp_server_credentials_t, in case - * of a server. - * - * For GNUTLS_CRD_CERTIFICATE cred should be gnutls_certificate_credentials_t. - * - **/ + * gnutls_credentials_set - Sets the needed credentials for the specified authentication algorithm. + * @session: is a #gnutls_session_t structure. + * @type: is the type of the credentials + * @cred: is a pointer to a structure. + * + * Sets the needed credentials for the specified type. Eg username, + * password - or public and private keys etc. The @cred parameter is + * a structure that depends on the specified type and on the current + * session (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_CRD_ANON, @cred should be + * #gnutls_anon_client_credentials_t in case of a client. In case of + * a server it should be #gnutls_anon_server_credentials_t. + * + * For %GNUTLS_CRD_SRP, @cred should be #gnutls_srp_client_credentials_t + * in case of a client, and #gnutls_srp_server_credentials_t, in case + * of a server. + * + * For %GNUTLS_CRD_CERTIFICATE, @cred should be + * #gnutls_certificate_credentials_t. + * + * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned, + * otherwise an error code is returned. + **/ int gnutls_credentials_set (gnutls_session_t session, gnutls_credentials_type_t type, void *cred) diff --git a/lib/gnutls_buffers.c b/lib/gnutls_buffers.c index b5fd10245f..0b94f6f173 100644 --- a/lib/gnutls_buffers.c +++ b/lib/gnutls_buffers.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation + * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -187,16 +187,18 @@ _gnutls_record_buffer_get_size (content_type_t type, gnutls_session_t session) } /** - * gnutls_record_check_pending - checks if there are any data to receive in gnutls buffers. - * @session: is a #gnutls_session_t structure. - * - * 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 - * a TCP connection, instead of this function. - * (gnutls leaves some data in the tcp buffer in order for select - * to work). - **/ + * gnutls_record_check_pending - checks if there are any data to receive in gnutls buffers. + * @session: is a #gnutls_session_t structure. + * + * This function checks if there are any data to receive in the gnutls + * buffers. + * + * Notice that you may also use select() to check for data in a TCP + * connection, instead of this function. GnuTLS leaves some data in + * the tcp buffer in order for select to work. + * + * Returns: the size of that data or 0. + **/ size_t gnutls_record_check_pending (gnutls_session_t session) { diff --git a/lib/gnutls_cert.c b/lib/gnutls_cert.c index 9d5b3f5ac7..40bcdf85ef 100644 --- a/lib/gnutls_cert.c +++ b/lib/gnutls_cert.c @@ -574,8 +574,8 @@ _gnutls_openpgp_crt_verify_peers (gnutls_session_t session, * Note that you must also check the peer's name in order to check if * the verified certificate belongs to the actual peer. * - * This is the same as gnutls_x509_crt_list_verify() and uses the - * loaded CAs in the credentials as trusted CAs. + * This function uses gnutls_x509_crt_list_verify() with the CAs in + * the credentials as trusted CAs. * * Note that some commonly used X.509 Certificate Authorities are * still using Version 1 certificates. If you want to accept them, @@ -623,11 +623,10 @@ gnutls_certificate_verify_peers2 (gnutls_session_t session, * the peer's name in order to check if the verified certificate * belongs to the actual peer. * - * The return value should be one or more of the - * gnutls_certificate_status_t enumerated elements bitwise or'd, or a - * negative value on error. + * This function uses gnutls_x509_crt_list_verify(). * - * This is the same as gnutls_x509_crt_list_verify(). + * Returns: one or more of the #gnutls_certificate_status_t + * enumerated elements bitwise or'd, or a negative value on error. * * Deprecated: Use gnutls_certificate_verify_peers2() instead. **/ diff --git a/lib/gnutls_global.c b/lib/gnutls_global.c index ece100bd84..6b149cfbb0 100644 --- a/lib/gnutls_global.c +++ b/lib/gnutls_global.c @@ -104,10 +104,8 @@ gnutls_global_set_log_level (int level) **/ void gnutls_global_set_mem_functions (gnutls_alloc_function alloc_func, - gnutls_alloc_function - secure_alloc_func, - gnutls_is_secure_function - is_secure_func, + gnutls_alloc_function secure_alloc_func, + gnutls_is_secure_function is_secure_func, gnutls_realloc_function realloc_func, gnutls_free_function free_func) { diff --git a/lib/gnutls_priority.c b/lib/gnutls_priority.c index a47b70acdc..314b51da8e 100644 --- a/lib/gnutls_priority.c +++ b/lib/gnutls_priority.c @@ -518,7 +518,8 @@ gnutls_priority_set (gnutls_session_t session, gnutls_priority_t priority) **/ int gnutls_priority_init (gnutls_priority_t * priority_cache, - const char *priorities, const char **err_pos) + const char *priorities, + const char **err_pos) { char *broken_list[MAX_ELEMENTS]; int broken_list_size, i, j; diff --git a/lib/gnutls_psk.c b/lib/gnutls_psk.c index 6c66bbe2c6..f0a49dda72 100644 --- a/lib/gnutls_psk.c +++ b/lib/gnutls_psk.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2005, 2007, 2008 Free Software Foundation + * Copyright (C) 2005, 2007, 2008, 2009 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -438,14 +438,14 @@ gnutls_psk_set_server_dh_params (gnutls_psk_server_credentials_t res, } /** - * gnutls_psk_set_server_params_function - set the DH 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 parameters for PSK authentication. The callback - * should return zero on success. - **/ + * gnutls_psk_set_server_params_function - set the DH 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 parameters for PSK authentication. The callback + * should return zero on success. + **/ void gnutls_psk_set_server_params_function (gnutls_psk_server_credentials_t res, gnutls_params_function * func) diff --git a/lib/gnutls_session.c b/lib/gnutls_session.c index 62a3cdcf71..2a3419b42d 100644 --- a/lib/gnutls_session.c +++ b/lib/gnutls_session.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2000, 2003, 2004, 2005, 2007, 2008 Free Software Foundation + * Copyright (C) 2000, 2003, 2004, 2005, 2007, 2008, 2009 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -83,22 +83,23 @@ error: } /** - * gnutls_session_get_data2 - Returns all session parameters. - * @session: is a #gnutls_session_t structure. - * @session_data: is a pointer to a datum that will hold the session. - * - * 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_session_set_data() - * This function must be called after a successful handshake. The returned - * datum must be freed with gnutls_free(). - * - * Resuming sessions is really useful and speedups connections after - * a succesful one. - * - * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise - * an error code is returned. - **/ + * gnutls_session_get_data2 - Returns all session parameters. + * @session: is a #gnutls_session_t structure. + * @data: is a pointer to a datum that will hold the session. + * + * 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_session_set_data(). This function must be called after a + * successful handshake. The returned datum must be freed with + * gnutls_free(). + * + * Resuming sessions is really useful and speedups connections after + * a succesful one. + * + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise + * an error code is returned. + **/ int gnutls_session_get_data2 (gnutls_session_t session, gnutls_datum_t * data) { diff --git a/lib/gnutls_state.c b/lib/gnutls_state.c index 31b0c84c7e..3dd440eccc 100644 --- a/lib/gnutls_state.c +++ b/lib/gnutls_state.c @@ -1123,7 +1123,7 @@ gnutls_session_get_master_secret (gnutls_session_t session) /** * gnutls_session_set_finished_function: * @session: is a #gnutls_session_t structure. - * @finished_func: a #gnutls_finished_callback_func callback. + * @func: a #gnutls_finished_callback_func callback. * * Register a callback function for the session that will be called * when a TLS Finished message has been generated. The function is @@ -1132,7 +1132,7 @@ gnutls_session_get_master_secret (gnutls_session_t session) * * The callback should follow this prototype: * - * void callback (gnutls_session_t session, const void *finished, size_t len); + * void callback (gnutls_session_t @session, const void *@finished, size_t @len); * * The @finished parameter will contain the binary TLS finished * message, and @len will contains its length. For SSLv3 connections, @@ -1147,10 +1147,9 @@ gnutls_session_get_master_secret (gnutls_session_t session) **/ void gnutls_session_set_finished_function (gnutls_session_t session, - gnutls_finished_callback_func - finished_func) + gnutls_finished_callback_func func) { - session->internals.finished_func = finished_func; + session->internals.finished_func = func; } /** @@ -1305,7 +1304,7 @@ _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 + * @session: is a #gnutls_session_t structure. * @func: is the function to be called * * This function will set a callback to be called after the client diff --git a/lib/includes/gnutls/gnutls.h.in b/lib/includes/gnutls/gnutls.h.in index ca3e206beb..bc4ada9208 100644 --- a/lib/includes/gnutls/gnutls.h.in +++ b/lib/includes/gnutls/gnutls.h.in @@ -330,8 +330,8 @@ extern "C" { GNUTLS_SIGN_RSA_SHA224 } gnutls_sign_algorithm_t; - const char *gnutls_sign_algorithm_get_name (gnutls_sign_algorithm_t - algorithm); + const char * + gnutls_sign_algorithm_get_name (gnutls_sign_algorithm_t sign); /* If you want to change this, then also change the define in * gnutls_int.h, and recompile. @@ -432,8 +432,8 @@ extern "C" { const gnutls_kx_algorithm_t *gnutls_kx_list (void); const gnutls_pk_algorithm_t *gnutls_pk_list (void); const gnutls_sign_algorithm_t *gnutls_sign_list (void); - const char *gnutls_cipher_suite_info (size_t i, - char *id, + const char *gnutls_cipher_suite_info (size_t idx, + char *cs_id, gnutls_kx_algorithm_t *kx, gnutls_cipher_algorithm_t *cipher, gnutls_mac_algorithm_t *mac, @@ -569,14 +569,14 @@ extern "C" { /* if you just want some defaults, use the following. */ int gnutls_priority_init (gnutls_priority_t *priority_cache, - const char *priority, + const char *priorities, const char** err_pos); - void gnutls_priority_deinit (gnutls_priority_t); + void gnutls_priority_deinit (gnutls_priority_t priority_cache); int gnutls_priority_set (gnutls_session_t session, gnutls_priority_t priority); int gnutls_priority_set_direct (gnutls_session_t session, - const char *priority, + const char *priorities, const char** err_pos); /* for compatibility @@ -585,12 +585,10 @@ extern "C" { int gnutls_set_default_export_priority (gnutls_session_t session); /* Returns the name of a cipher suite */ - const char *gnutls_cipher_suite_get_name (gnutls_kx_algorithm_t - kx_algorithm, - gnutls_cipher_algorithm_t - cipher_algorithm, - gnutls_mac_algorithm_t - mac_algorithm); + const char * + gnutls_cipher_suite_get_name (gnutls_kx_algorithm_t kx_algorithm, + gnutls_cipher_algorithm_t cipher_algorithm, + gnutls_mac_algorithm_t mac_algorithm); /* get the currently used protocol version */ gnutls_protocol_t gnutls_protocol_get_version (gnutls_session_t session); @@ -627,8 +625,7 @@ extern "C" { size_t len); void gnutls_session_set_finished_function (gnutls_session_t session, - gnutls_finished_callback_func - finished_func); + gnutls_finished_callback_func func); /* checks if this session is a resumed one */ @@ -817,13 +814,12 @@ extern "C" { typedef void (*gnutls_free_function) (void *); typedef void *(*gnutls_realloc_function) (void *, size_t); - void gnutls_global_set_mem_functions (gnutls_alloc_function gt_alloc_func, - gnutls_alloc_function - gt_secure_alloc_func, - gnutls_is_secure_function - gt_is_secure_func, - gnutls_realloc_function gt_realloc_func, - gnutls_free_function gt_free_func); + void + gnutls_global_set_mem_functions (gnutls_alloc_function alloc_func, + gnutls_alloc_function secure_alloc_func, + gnutls_is_secure_function is_secure_func, + gnutls_realloc_function realloc_func, + gnutls_free_function free_func); /* For use in callbacks */ extern gnutls_alloc_function gnutls_malloc; @@ -1053,9 +1049,9 @@ extern "C" { const char *username, gnutls_datum_t * key); void - gnutls_psk_set_server_credentials_function - (gnutls_psk_server_credentials_t cred, - gnutls_psk_server_credentials_function * func); + gnutls_psk_set_server_credentials_function + (gnutls_psk_server_credentials_t cred, + gnutls_psk_server_credentials_function * func); typedef int gnutls_psk_client_credentials_function (gnutls_session_t, char **username, @@ -1070,12 +1066,13 @@ extern "C" { int gnutls_hex_decode (const gnutls_datum_t * hex_data, char *result, size_t * result_size); - void gnutls_psk_set_server_dh_params (gnutls_psk_server_credentials_t res, - gnutls_dh_params_t dh_params); + void + gnutls_psk_set_server_dh_params (gnutls_psk_server_credentials_t res, + gnutls_dh_params_t dh_params); - void gnutls_psk_set_server_params_function (gnutls_psk_server_credentials_t - res, - gnutls_params_function * func); + void + gnutls_psk_set_server_params_function (gnutls_psk_server_credentials_t res, + gnutls_params_function * func); int gnutls_psk_netconf_derive_key (const char *password, const char *psk_identity, diff --git a/lib/includes/gnutls/openpgp.h b/lib/includes/gnutls/openpgp.h index 56373e278a..c75915e93b 100644 --- a/lib/includes/gnutls/openpgp.h +++ b/lib/includes/gnutls/openpgp.h @@ -69,7 +69,7 @@ extern "C" /* The key_usage flags are defined in gnutls.h. They are * the GNUTLS_KEY_* definitions. */ - int gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t cert, + int gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t key, unsigned int *key_usage); int gnutls_openpgp_crt_get_fingerprint (gnutls_openpgp_crt_t key, void *fpr, size_t * fprlen); @@ -153,7 +153,8 @@ extern "C" int gnutls_openpgp_privkey_import (gnutls_openpgp_privkey_t key, const gnutls_datum_t * data, gnutls_openpgp_crt_fmt_t format, - const char *pass, unsigned int flags); + const char *password, + unsigned int flags); int gnutls_openpgp_privkey_sign_hash (gnutls_openpgp_privkey_t key, const gnutls_datum_t * hash, gnutls_datum_t * signature); @@ -287,6 +288,8 @@ extern "C" * fingerprint instead of a full key. See also * gnutls_openpgp_set_recv_key_function(). * + * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned, + * otherwise an error code is returned. */ typedef int (*gnutls_openpgp_recv_key_func) (gnutls_session_t session, const unsigned char *keyfpr, @@ -309,24 +312,24 @@ extern "C" gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t res, const char *certfile, const char *keyfile, - gnutls_openpgp_crt_fmt_t); + gnutls_openpgp_crt_fmt_t format); int gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t res, const gnutls_datum_t * cert, const gnutls_datum_t * key, - gnutls_openpgp_crt_fmt_t); + gnutls_openpgp_crt_fmt_t format); int gnutls_certificate_set_openpgp_key_file2 (gnutls_certificate_credentials_t res, const char *certfile, const char *keyfile, - const char *keyid, + const char *subkey_id, gnutls_openpgp_crt_fmt_t format); int gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t res, const gnutls_datum_t * cert, const gnutls_datum_t * key, - const char *keyid, + const char *subkey_id, gnutls_openpgp_crt_fmt_t format); int diff --git a/lib/includes/gnutls/pkcs12.h b/lib/includes/gnutls/pkcs12.h index fcd6a49291..d0d94cb695 100644 --- a/lib/includes/gnutls/pkcs12.h +++ b/lib/includes/gnutls/pkcs12.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2003, 2004, 2005, 2007, 2008 Free Software Foundation + * Copyright (C) 2003, 2004, 2005, 2007, 2008, 2009 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -72,8 +72,9 @@ extern "C" GNUTLS_BAG_UNKNOWN = 20 } gnutls_pkcs12_bag_type_t; - gnutls_pkcs12_bag_type_t gnutls_pkcs12_bag_get_type (gnutls_pkcs12_bag_t - bag, int indx); + gnutls_pkcs12_bag_type_t + gnutls_pkcs12_bag_get_type (gnutls_pkcs12_bag_t bag, + int indx); int gnutls_pkcs12_bag_get_data (gnutls_pkcs12_bag_t bag, int indx, gnutls_datum_t * data); int gnutls_pkcs12_bag_set_data (gnutls_pkcs12_bag_t bag, diff --git a/lib/includes/gnutls/x509.h b/lib/includes/gnutls/x509.h index 5dc386d398..0abb5867e0 100644 --- a/lib/includes/gnutls/x509.h +++ b/lib/includes/gnutls/x509.h @@ -271,11 +271,14 @@ extern "C" const void *data, unsigned int data_size, unsigned int flags); - int gnutls_x509_crt_sign (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer, + int gnutls_x509_crt_sign (gnutls_x509_crt_t crt, + gnutls_x509_crt_t issuer, gnutls_x509_privkey_t issuer_key); - int gnutls_x509_crt_sign2 (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer, + int gnutls_x509_crt_sign2 (gnutls_x509_crt_t crt, + gnutls_x509_crt_t issuer, gnutls_x509_privkey_t issuer_key, - gnutls_digest_algorithm_t, unsigned int flags); + gnutls_digest_algorithm_t dig, + unsigned int flags); int gnutls_x509_crt_set_activation_time (gnutls_x509_crt_t cert, time_t act_time); int gnutls_x509_crt_set_expiration_time (gnutls_x509_crt_t cert, diff --git a/lib/openpgp/extras.c b/lib/openpgp/extras.c index 00fd9d0c6e..bf0ec39733 100644 --- a/lib/openpgp/extras.c +++ b/lib/openpgp/extras.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2003, 2004, 2005, 2007, 2008 Free Software Foundation + * Copyright (C) 2003, 2004, 2005, 2007, 2008, 2009 Free Software Foundation * * Author: Nikos Mavrogiannopoulos, Timo Schulz * @@ -256,9 +256,9 @@ gnutls_openpgp_keyring_get_crt_count (gnutls_openpgp_keyring_t ring) /** * gnutls_openpgp_keyring_get_crt - export an openpgp certificate from a keyring - * @key: Holds the key. + * @ring: Holds the keyring. * @idx: the index of the certificate to export - * @crt: An uninitialized #gnutls_openpgp_crt_t structure + * @cert: An uninitialized #gnutls_openpgp_crt_t structure * * This function will extract an OpenPGP certificate from the given * keyring. If the index given is out of range diff --git a/lib/openpgp/gnutls_openpgp.c b/lib/openpgp/gnutls_openpgp.c index ddb4baae42..cda68a51c7 100644 --- a/lib/openpgp/gnutls_openpgp.c +++ b/lib/openpgp/gnutls_openpgp.c @@ -115,22 +115,24 @@ _gnutls_openpgp_raw_crt_to_gcert (gnutls_cert * gcert, } /** - * gnutls_certificate_set_openpgp_key - Used to set keys in a gnutls_certificate_credentials_t structure - * @res: is an #gnutls_certificate_credentials_t structure. - * @key: contains an openpgp public key - * @pkey: is an openpgp private key - * - * This function sets a certificate/private key pair in the - * gnutls_certificate_credentials_t structure. This function may be called - * more than once (in case multiple keys/certificates exist for the - * server). - * - * With this function the subkeys of the certificate are not used. - * - **/ + * gnutls_certificate_set_openpgp_key - Used to set keys in a gnutls_certificate_credentials_t structure + * @res: is an #gnutls_certificate_credentials_t structure. + * @key: contains an openpgp public key + * @pkey: is an openpgp private key + * + * This function sets a certificate/private key pair in the + * gnutls_certificate_credentials_t structure. This function may be + * called more than once (in case multiple keys/certificates exist + * for the server). + * + * With this function the subkeys of the certificate are not used. + * + * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned, + * otherwise an error code is returned. + **/ int -gnutls_certificate_set_openpgp_key (gnutls_certificate_credentials_t - res, gnutls_openpgp_crt_t crt, +gnutls_certificate_set_openpgp_key (gnutls_certificate_credentials_t res, + gnutls_openpgp_crt_t crt, gnutls_openpgp_privkey_t pkey) { int ret; @@ -283,12 +285,12 @@ leave: * negative error value. **/ int -gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t - res, const gnutls_datum_t * icert, - const gnutls_datum_t * ikey, +gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t res, + const gnutls_datum_t * cert, + const gnutls_datum_t * key, gnutls_openpgp_crt_fmt_t format) { - return gnutls_certificate_set_openpgp_key_mem2 (res, icert, ikey, + return gnutls_certificate_set_openpgp_key_mem2 (res, cert, key, NULL, format); } @@ -308,8 +310,8 @@ gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t * negative error value. **/ int -gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t - res, const char *certfile, +gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t res, + const char *certfile, const char *keyfile, gnutls_openpgp_crt_fmt_t format) { @@ -350,7 +352,7 @@ get_keyid (gnutls_openpgp_keyid_t keyid, const char *str) * credentials structure. The files should only contain one key which * is not encrypted. * - * The special keyword "auto" is also accepted as &subkey_id. In that + * The special keyword "auto" is also accepted as @subkey_id. In that * case the gnutls_openpgp_crt_get_auth_subkey() will be used to * retrieve the subkey. * @@ -360,45 +362,45 @@ get_keyid (gnutls_openpgp_keyid_t keyid, const char *str) * Since: 2.4.0 **/ int -gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t - res, const gnutls_datum_t * icert, - const gnutls_datum_t * ikey, +gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t res, + const gnutls_datum_t * cert, + const gnutls_datum_t * key, const char *subkey_id, gnutls_openpgp_crt_fmt_t format) { - gnutls_openpgp_privkey_t key; - gnutls_openpgp_crt_t cert; + gnutls_openpgp_privkey_t pkey; + gnutls_openpgp_crt_t crt; int ret; - ret = gnutls_openpgp_privkey_init (&key); + ret = gnutls_openpgp_privkey_init (&pkey); if (ret < 0) { gnutls_assert (); return ret; } - ret = gnutls_openpgp_privkey_import (key, ikey, format, NULL, 0); + ret = gnutls_openpgp_privkey_import (pkey, key, format, NULL, 0); if (ret < 0) { gnutls_assert (); - gnutls_openpgp_privkey_deinit (key); + gnutls_openpgp_privkey_deinit (pkey); return ret; } - ret = gnutls_openpgp_crt_init (&cert); + ret = gnutls_openpgp_crt_init (&crt); if (ret < 0) { gnutls_assert (); - gnutls_openpgp_privkey_deinit (key); + gnutls_openpgp_privkey_deinit (pkey); return ret; } - ret = gnutls_openpgp_crt_import (cert, icert, format); + ret = gnutls_openpgp_crt_import (crt, cert, format); if (ret < 0) { gnutls_assert (); - gnutls_openpgp_privkey_deinit (key); - gnutls_openpgp_crt_deinit (cert); + gnutls_openpgp_privkey_deinit (pkey); + gnutls_openpgp_crt_deinit (crt); return ret; } @@ -407,30 +409,30 @@ gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t gnutls_openpgp_keyid_t keyid; if (strcasecmp (subkey_id, "auto") == 0) - ret = gnutls_openpgp_crt_get_auth_subkey (cert, keyid, 1); + ret = gnutls_openpgp_crt_get_auth_subkey (crt, keyid, 1); else ret = get_keyid (keyid, subkey_id); if (ret >= 0) { - ret = gnutls_openpgp_crt_set_preferred_key_id (cert, keyid); + ret = gnutls_openpgp_crt_set_preferred_key_id (crt, keyid); if (ret >= 0) - ret = gnutls_openpgp_privkey_set_preferred_key_id (key, keyid); + ret = gnutls_openpgp_privkey_set_preferred_key_id (pkey, keyid); } if (ret < 0) { gnutls_assert (); - gnutls_openpgp_privkey_deinit (key); - gnutls_openpgp_crt_deinit (cert); + gnutls_openpgp_privkey_deinit (pkey); + gnutls_openpgp_crt_deinit (crt); return ret; } } - ret = gnutls_certificate_set_openpgp_key (res, cert, key); + ret = gnutls_certificate_set_openpgp_key (res, crt, pkey); - gnutls_openpgp_privkey_deinit (key); - gnutls_openpgp_crt_deinit (cert); + gnutls_openpgp_privkey_deinit (pkey); + gnutls_openpgp_crt_deinit (crt); return ret; } @@ -447,8 +449,9 @@ gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t * This funtion is used to load OpenPGP keys into the GnuTLS credential * structure. The files should contain non encrypted keys. * - * The special keyword "auto" is also accepted as &subkey_id. In that case - * the gnutls_openpgp_crt_get_auth_subkey() will be used to retrieve the subkey. + * The special keyword "auto" is also accepted as @subkey_id. In that + * case the gnutls_openpgp_crt_get_auth_subkey() will be used to + * retrieve the subkey. * * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a * negative error value. @@ -599,6 +602,7 @@ gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t c, * @c: A certificate credentials structure * @data: buffer with keyring data. * @dlen: length of data buffer. + * @format: the format of the keyring * * The function is used to set keyrings that will be used internally * by various OpenPGP functions. For example to find a key when it @@ -609,8 +613,8 @@ gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t c, * negative error value. **/ int -gnutls_certificate_set_openpgp_keyring_mem (gnutls_certificate_credentials_t - c, const opaque * data, +gnutls_certificate_set_openpgp_keyring_mem (gnutls_certificate_credentials_t c, + const opaque * data, size_t dlen, gnutls_openpgp_crt_fmt_t format) { diff --git a/lib/openpgp/pgp.c b/lib/openpgp/pgp.c index 09ae1047c9..d6182e80a8 100644 --- a/lib/openpgp/pgp.c +++ b/lib/openpgp/pgp.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation + * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation * * Author: Timo Schulz, Nikos Mavrogiannopoulos * @@ -1549,6 +1549,8 @@ gnutls_openpgp_crt_get_preferred_key_id (gnutls_openpgp_crt_t key, * This allows setting a preferred key id for the given certificate. * This key will be used by functions that involve key handling. * + * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned, + * otherwise an error code is returned. **/ int gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t key, @@ -1579,7 +1581,7 @@ gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t key, /** * gnutls_openpgp_crt_get_auth_subkey - Gets the keyID of an authentication subkey - * @key: the structure that contains the OpenPGP public key. + * @crt: the structure that contains the OpenPGP public key. * @keyid: the struct to save the keyid. * @flag: Non zero indicates that a valid subkey is always returned. * diff --git a/lib/openpgp/privkey.c b/lib/openpgp/privkey.c index 2aff7dee3d..d84a35fcc7 100644 --- a/lib/openpgp/privkey.c +++ b/lib/openpgp/privkey.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation + * Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -77,8 +77,8 @@ gnutls_openpgp_privkey_deinit (gnutls_openpgp_privkey_t key) * gnutls_openpgp_privkey_import - import a RAW or BASE64 encoded key * @key: The structure to store the parsed key. * @data: The RAW or BASE64 encoded key. - * @format: One of gnutls_openpgp_crt_fmt_t elements. - * @password: (unused for now) + * @format: One of #gnutls_openpgp_crt_fmt_t elements. + * @password: not used for now * @flags: should be zero * * This function will convert the given RAW or Base64 encoded key to diff --git a/lib/x509/crq.c b/lib/x509/crq.c index 3014ed8d33..67ecdbc2a4 100644 --- a/lib/x509/crq.c +++ b/lib/x509/crq.c @@ -2004,6 +2004,7 @@ gnutls_x509_crq_set_key_usage (gnutls_x509_crq_t crq, unsigned int usage) * @indx: This specifies which OID to return. Use zero to get the first one. * @oid: a pointer to a buffer to hold the OID (may be null) * @sizeof_oid: initially holds the size of @oid + * @critical: output variable with critical flag, may be NULL. * * This function will extract the key purpose OIDs of the Certificate * specified by the given index. These are stored in the Extended diff --git a/lib/x509/dn.c b/lib/x509/dn.c index 7ce6df2712..662fd9f236 100644 --- a/lib/x509/dn.c +++ b/lib/x509/dn.c @@ -977,7 +977,6 @@ gnutls_x509_dn_init (gnutls_x509_dn_t * dn) /** * gnutls_x509_dn_import: get opaque DN object from DER RDN sequence - * * @dn: the structure that will hold the imported DN * @data: should contain a DER encoded RDN sequence * diff --git a/lib/x509/pkcs12_bag.c b/lib/x509/pkcs12_bag.c index 42bc8f2075..3a5bb89a23 100644 --- a/lib/x509/pkcs12_bag.c +++ b/lib/x509/pkcs12_bag.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2003, 2004, 2005, 2008 Free Software Foundation + * Copyright (C) 2003, 2004, 2005, 2008, 2009 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -95,14 +95,14 @@ gnutls_pkcs12_bag_deinit (gnutls_pkcs12_bag_t bag) } /** - * gnutls_pkcs12_bag_get_type - This function returns the bag's type - * @bag: The bag - * @indx: The element of the bag to get the type - * - * This function will return the bag's type. One of the gnutls_pkcs12_bag_type_t - * enumerations. - * - **/ + * gnutls_pkcs12_bag_get_type - This function returns the bag's type + * @bag: The bag + * @indx: The element of the bag to get the type + * + * This function will return the bag's type. + * + * Returns: One of the #gnutls_pkcs12_bag_type_t enumerations. + **/ gnutls_pkcs12_bag_type_t gnutls_pkcs12_bag_get_type (gnutls_pkcs12_bag_t bag, int indx) { @@ -118,12 +118,14 @@ gnutls_pkcs12_bag_get_type (gnutls_pkcs12_bag_t bag, int indx) } /** - * gnutls_pkcs12_bag_get_count - This function returns the bag's elements count - * @bag: The bag - * - * This function will return the number of the elements withing the bag. - * - **/ + * gnutls_pkcs12_bag_get_count - This function returns the bag's elements count + * @bag: The bag + * + * This function will return the number of the elements withing the bag. + * + * Returns: Number of elements in bag, or an negative error code on + * error. + **/ int gnutls_pkcs12_bag_get_count (gnutls_pkcs12_bag_t bag) { @@ -622,13 +624,16 @@ gnutls_pkcs12_bag_set_friendly_name (gnutls_pkcs12_bag_t bag, int indx, /** - * gnutls_pkcs12_bag_decrypt - This function will decrypt an encrypted bag - * @bag: The bag - * @pass: The password used for encryption. This can only be ASCII. - * - * This function will decrypt the given encrypted bag and return 0 on success. - * - **/ + * gnutls_pkcs12_bag_decrypt - This function will decrypt an encrypted bag + * @bag: The bag + * @pass: The password used for encryption, must be ASCII. + * + * This function will decrypt the given encrypted bag and return 0 on + * success. + * + * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned, + * otherwise an error code is returned. + **/ int gnutls_pkcs12_bag_decrypt (gnutls_pkcs12_bag_t bag, const char *pass) { @@ -675,14 +680,16 @@ gnutls_pkcs12_bag_decrypt (gnutls_pkcs12_bag_t bag, const char *pass) } /** - * gnutls_pkcs12_bag_encrypt - This function will encrypt a bag - * @bag: The bag - * @pass: The password used for encryption. This can only be ASCII. - * @flags: should be one of gnutls_pkcs_encrypt_flags_t elements bitwise or'd - * - * This function will encrypt the given bag and return 0 on success. - * - **/ + * gnutls_pkcs12_bag_encrypt - This function will encrypt a bag + * @bag: The bag + * @pass: The password used for encryption, must be ASCII + * @flags: should be one of #gnutls_pkcs_encrypt_flags_t elements bitwise or'd + * + * This function will encrypt the given bag. + * + * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned, + * otherwise an error code is returned. + **/ int gnutls_pkcs12_bag_encrypt (gnutls_pkcs12_bag_t bag, const char *pass, unsigned int flags) diff --git a/lib/x509/x509.c b/lib/x509/x509.c index 86ce2d2b0b..1f6616deb3 100644 --- a/lib/x509/x509.c +++ b/lib/x509/x509.c @@ -1541,20 +1541,20 @@ gnutls_x509_crt_get_extension_by_oid (gnutls_x509_crt_t cert, } /** - * gnutls_x509_crt_get_extension_oid - This function returns the specified extension OID - * @cert: should contain a #gnutls_x509_crt_t structure - * @indx: Specifies which extension OID to send. Use zero to get the first one. - * @oid: a pointer to a structure to hold the OID (may be null) - * @sizeof_oid: initially holds the size of @oid - * - * This function will return the requested extension OID in the certificate. - * The extension OID will be stored as a string in the provided buffer. - * - * A negative value may be returned in case of parsing error. - * If your have reached the last extension available - * GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. - * - **/ + * gnutls_x509_crt_get_extension_oid - get the specified extension OID + * @cert: should contain a #gnutls_x509_crt_t structure + * @indx: Specifies which extension OID to send. Use zero to get the first one. + * @oid: a pointer to a structure to hold the OID (may be null) + * @sizeof_oid: initially holds the size of @oid + * + * This function will return the requested extension OID in the certificate. + * The extension OID will be stored as a string in the provided buffer. + * + * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned, + * otherwise an error code is returned. If you have reached the + * last extension available %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE + * will be returned. + **/ int gnutls_x509_crt_get_extension_oid (gnutls_x509_crt_t cert, int indx, void *oid, size_t * sizeof_oid) @@ -1669,9 +1669,10 @@ gnutls_x509_crt_get_extension_info (gnutls_x509_crt_t cert, int indx, * if you want to get data indexed by the extension OID rather than * sequence. * - * Return 0 on success. A negative value may be returned in case of - * parsing error. If you have reached the last extension available - * GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. + * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned, + * otherwise an error code is returned. If you have reached the + * last extension available %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE + * will be returned. **/ int gnutls_x509_crt_get_extension_data (gnutls_x509_crt_t cert, int indx, diff --git a/lib/x509/x509_write.c b/lib/x509/x509_write.c index 6ee514a94a..f19502db00 100644 --- a/lib/x509/x509_write.c +++ b/lib/x509/x509_write.c @@ -1169,11 +1169,13 @@ gnutls_x509_crt_set_authority_key_id (gnutls_x509_crt_t cert, * * Subsequent calls to this function will append OIDs to the OID list. * - * On success 0 is returned. + * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned, + * otherwise an error code is returned. **/ int gnutls_x509_crt_set_key_purpose_oid (gnutls_x509_crt_t cert, - const void *oid, unsigned int critical) + const void *oid, + unsigned int critical) { int result; gnutls_datum_t old_id, der_data; diff --git a/libextra/gnutls_ia.c b/libextra/gnutls_ia.c index cbc1c63640..4e2c633aca 100644 --- a/libextra/gnutls_ia.c +++ b/libextra/gnutls_ia.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2005, 2006, 2008 Free Software Foundation + * Copyright (C) 2005, 2006, 2008, 2009 Free Software Foundation * * Author: Simon Josefsson * @@ -9,12 +9,12 @@ * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. - * + * * GNUTLS-EXTRA is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. - * + * * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ @@ -635,7 +635,8 @@ gnutls_ia_handshake_p (gnutls_session_t session) * Perform a TLS/IA handshake. This should be called after * gnutls_handshake() iff gnutls_ia_handshake_p(). * - * Return 0 on success, or an error code. + * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned, + * otherwise an error code is returned. **/ int gnutls_ia_handshake (gnutls_session_t session) -- cgit v1.2.1