diff options
author | Simon Josefsson <simon@josefsson.org> | 2008-04-28 18:14:14 +0200 |
---|---|---|
committer | Simon Josefsson <simon@josefsson.org> | 2008-04-28 18:14:14 +0200 |
commit | 02393bd4ef0c2ee7864c356f70623f3950f372f0 (patch) | |
tree | 2de9dcb9c76c2f706293b8657c2627a0fed07b74 | |
parent | d378601cfe953eb3257c1530e49d98a31c07c863 (diff) | |
download | gnutls-02393bd4ef0c2ee7864c356f70623f3950f372f0.tar.gz |
Doc fixes.
-rw-r--r-- | lib/openpgp/extras.c | 66 | ||||
-rw-r--r-- | lib/openpgp/output.c | 22 | ||||
-rw-r--r-- | lib/openpgp/pgp.c | 397 | ||||
-rw-r--r-- | lib/openpgp/pgpverify.c | 35 | ||||
-rw-r--r-- | lib/openpgp/privkey.c | 195 | ||||
-rw-r--r-- | lib/x509/rfc2818_hostname.c | 23 |
6 files changed, 370 insertions, 368 deletions
diff --git a/lib/openpgp/extras.c b/lib/openpgp/extras.c index 56ff449c19..1bbf6a1d92 100644 --- a/lib/openpgp/extras.c +++ b/lib/openpgp/extras.c @@ -37,13 +37,12 @@ */ /** - * gnutls_openpgp_keyring_init - This function initializes a gnutls_openpgp_keyring_t structure + * gnutls_openpgp_keyring_init - initializes a #gnutls_openpgp_keyring_t structure * @keyring: The structure to be initialized * - * This function will initialize an keyring structure. - * - * Returns 0 on success. + * This function will initialize an keyring structure. * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_openpgp_keyring_init (gnutls_openpgp_keyring_t * keyring) @@ -57,11 +56,10 @@ gnutls_openpgp_keyring_init (gnutls_openpgp_keyring_t * keyring) /** - * gnutls_openpgp_keyring_deinit - This function deinitializes memory used by a gnutls_openpgp_keyring_t structure + * gnutls_openpgp_keyring_deinit - deinitializes memory used by a #gnutls_openpgp_keyring_t structure * @keyring: The structure to be initialized * - * This function will deinitialize a keyring structure. - * + * This function will deinitialize a keyring structure. **/ void gnutls_openpgp_keyring_deinit (gnutls_openpgp_keyring_t keyring) @@ -86,8 +84,8 @@ gnutls_openpgp_keyring_deinit (gnutls_openpgp_keyring_t keyring) * * Check if a given key ID exists in the keyring. * - * Returns 0 on success (if keyid exists) and a negative error code - * on failure. + * Returns: %GNUTLS_E_SUCCESS on success (if keyid exists) and a + * negative error code on failure. **/ int gnutls_openpgp_keyring_check_id (gnutls_openpgp_keyring_t ring, @@ -116,12 +114,11 @@ gnutls_openpgp_keyring_check_id (gnutls_openpgp_keyring_t ring, * @data: The RAW or BASE64 encoded keyring. * @format: One of #gnutls_openpgp_keyring_fmt elements. * - * This function will convert the given RAW or Base64 encoded keyring to the - * native #gnutls_openpgp_keyring_t format. The output will be stored in - * 'keyring'. - * - * Returns 0 on success. + * This function will convert the given RAW or Base64 encoded keyring + * to the native #gnutls_openpgp_keyring_t format. The output will be + * stored in 'keyring'. * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_openpgp_keyring_import (gnutls_openpgp_keyring_t keyring, @@ -219,15 +216,14 @@ error: cdk_kbnode_find_packet (node, CDK_PKT_PUBLIC_KEY)!=NULL /** - * gnutls_openpgp_keyring_get_crt_count - This function returns the number of certificates - * @ring: is an OpenPGP key ring - * - * This function will return the number of OpenPGP certificates present in the given - * keyring. - * - * Returns then number of subkeys or a negative value on error. - * - **/ + * gnutls_openpgp_keyring_get_crt_count - return the number of certificates + * @ring: is an OpenPGP key ring + * + * This function will return the number of OpenPGP certificates + * present in the given keyring. + * + * Returns: the number of subkeys, or a negative value on error. + **/ int gnutls_openpgp_keyring_get_crt_count (gnutls_openpgp_keyring_t ring) { @@ -266,18 +262,18 @@ gnutls_openpgp_keyring_get_crt_count (gnutls_openpgp_keyring_t ring) } /** - * gnutls_openpgp_keyring_get_crt - This function will export an openpgp certificate from a keyring - * @key: Holds the key. - * @idx: the index of the certificate to export - * @crt: 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 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be - * returned. The returned structure needs to be deinited. - * - * Returns 0 on success. - * - **/ + * gnutls_openpgp_keyring_get_crt - export an openpgp certificate from a keyring + * @key: Holds the key. + * @idx: the index of the certificate to export + * @crt: 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 + * %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. The + * returned structure needs to be deinited. + * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. + **/ int gnutls_openpgp_keyring_get_crt (gnutls_openpgp_keyring_t ring, unsigned int idx, diff --git a/lib/openpgp/output.c b/lib/openpgp/output.c index c5b3276c67..485cf7598f 100644 --- a/lib/openpgp/output.c +++ b/lib/openpgp/output.c @@ -325,15 +325,17 @@ size_t dn_size; dn_size = sizeof(dn); err = gnutls_openpgp_crt_get_name (cert, i++, dn, &dn_size); - if (err < 0 && err != GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE && err != GNUTLS_E_OPENPGP_UID_REVOKED) { - addf (str, "error: get_name: %s %d\n", gnutls_strerror (err), err); - break; - } + if (err < 0 && err != GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE && + err != GNUTLS_E_OPENPGP_UID_REVOKED) + { + addf (str, "error: get_name: %s %d\n", gnutls_strerror (err), err); + break; + } if (err >= 0) addf (str, _("\tName[%d]: %s\n"), i-1, dn); else if (err == GNUTLS_E_OPENPGP_UID_REVOKED) { - addf (str, _("\tRevoked Name[%d]: %s\n"), i-1, dn); + addf (str, _("\tRevoked Name[%d]: %s\n"), i-1, dn); } } while( err >= 0); @@ -346,10 +348,10 @@ size_t dn_size; subkeys = gnutls_openpgp_crt_get_subkey_count( cert); if (subkeys < 0) return; - + for (i=0;i<subkeys;i++) { addf( str, _("\n\tSubkey[%d]:\n"), i); - + print_key_revoked( str, cert, i); print_key_id( str, cert, i); print_key_times( str, cert, i); @@ -365,14 +367,14 @@ size_t dn_size; * @format: Indicate the format to use * @out: Newly allocated datum with zero terminated string. * - * This function will pretty print an OpenPGP certificate, suitable for - * display to a human. + * This function will pretty print an OpenPGP certificate, suitable + * for display to a human. * * The format should be zero for future compatibility. * * The output @out needs to be deallocate using gnutls_free(). * - * Returns 0 on success. + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_openpgp_crt_print (gnutls_openpgp_crt_t cert, diff --git a/lib/openpgp/pgp.c b/lib/openpgp/pgp.c index 55a88b35e5..50609e406e 100644 --- a/lib/openpgp/pgp.c +++ b/lib/openpgp/pgp.c @@ -34,13 +34,12 @@ #include <gnutls_num.h> /** - * gnutls_openpgp_crt_init - This function initializes a gnutls_openpgp_crt_t structure + * gnutls_openpgp_crt_init - initialize a #gnutls_openpgp_crt_t structure * @key: The structure to be initialized * - * This function will initialize an OpenPGP key structure. - * - * Returns 0 on success. + * This function will initialize an OpenPGP key structure. * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_openpgp_crt_init (gnutls_openpgp_crt_t * key) @@ -53,10 +52,10 @@ gnutls_openpgp_crt_init (gnutls_openpgp_crt_t * key) } /** - * gnutls_openpgp_crt_deinit - This function deinitializes memory used by a gnutls_openpgp_crt_t structure + * gnutls_openpgp_crt_deinit - deinitialize memory used by a #gnutls_openpgp_crt_t structure * @key: The structure to be initialized * - * This function will deinitialize a key structure. + * This function will deinitialize a key structure. **/ void gnutls_openpgp_crt_deinit (gnutls_openpgp_crt_t key) @@ -69,21 +68,22 @@ gnutls_openpgp_crt_deinit (gnutls_openpgp_crt_t key) cdk_kbnode_release (key->knode); key->knode = NULL; } - + gnutls_free (key); } /** - * gnutls_openpgp_crt_import - This function will 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. - * - * This function will convert the given RAW or Base64 encoded key - * to the native gnutls_openpgp_crt_t format. The output will be stored in 'key'. - * - * Returns 0 on success. - **/ + * gnutls_openpgp_crt_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. + * + * This function will convert the given RAW or Base64 encoded key to + * the native #gnutls_openpgp_crt_t format. The output will be stored + * in 'key'. + * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. + **/ int gnutls_openpgp_crt_import (gnutls_openpgp_crt_t key, const gnutls_datum_t * data, @@ -109,7 +109,7 @@ gnutls_openpgp_crt_import (gnutls_openpgp_crt_t key, rc = _gnutls_map_cdk_rc (rc); gnutls_assert (); return rc; - } + } if (cdk_armor_filter_use (inp)) rc = cdk_stream_set_armor_flag (inp, 0); if (!rc) @@ -140,8 +140,10 @@ gnutls_openpgp_crt_import (gnutls_openpgp_crt_t key, /* internal version of export */ int _gnutls_openpgp_export (cdk_kbnode_t node, - gnutls_openpgp_crt_fmt_t format, - void *output_data, size_t * output_data_size, int private) + gnutls_openpgp_crt_fmt_t format, + void *output_data, + size_t * output_data_size, + int private) { size_t input_data_size = *output_data_size; size_t calc_size; @@ -154,10 +156,10 @@ int _gnutls_openpgp_export (cdk_kbnode_t node, gnutls_assert (); return rc; } - + /* If the caller uses output_data == NULL then return what he expects. */ - if (!output_data) + if (!output_data) { gnutls_assert(); return GNUTLS_E_SHORT_MEMORY_BUFFER; @@ -167,7 +169,7 @@ int _gnutls_openpgp_export (cdk_kbnode_t node, { unsigned char *in = cdk_calloc (1, *output_data_size); memcpy (in, output_data, *output_data_size); - + /* Calculate the size of the encoded data and check if the provided buffer is large enough. */ rc = cdk_armor_encode_buffer (in, *output_data_size, @@ -179,7 +181,7 @@ int _gnutls_openpgp_export (cdk_kbnode_t node, gnutls_assert (); return GNUTLS_E_SHORT_MEMORY_BUFFER; } - + rc = cdk_armor_encode_buffer (in, *output_data_size, output_data, input_data_size, &calc_size, private?CDK_ARMOR_SECKEY:CDK_ARMOR_PUBKEY); @@ -192,25 +194,26 @@ int _gnutls_openpgp_export (cdk_kbnode_t node, } /** - * gnutls_openpgp_crt_export - This function will export a RAW or BASE64 encoded key - * @key: Holds the key. - * @format: One of gnutls_openpgp_crt_fmt_t elements. - * @output_data: will contain the key base64 encoded or raw - * @output_data_size: holds the size of output_data (and will be replaced by the actual size of parameters) - * - * This function will convert the given key to RAW or Base64 format. - * If the buffer provided is not long enough to hold the output, then - * GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. - * - * Returns 0 on success. - * - **/ + * gnutls_openpgp_crt_export - export a RAW or BASE64 encoded key + * @key: Holds the key. + * @format: One of gnutls_openpgp_crt_fmt_t elements. + * @output_data: will contain the key base64 encoded or raw + * @output_data_size: holds the size of output_data (and will + * be replaced by the actual size of parameters) + * + * This function will convert the given key to RAW or Base64 format. + * If the buffer provided is not long enough to hold the output, then + * %GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. + * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. + **/ int gnutls_openpgp_crt_export (gnutls_openpgp_crt_t key, gnutls_openpgp_crt_fmt_t format, void *output_data, size_t * output_data_size) { - return _gnutls_openpgp_export( key->knode, format, output_data, output_data_size, 0); + return _gnutls_openpgp_export( key->knode, format, output_data, + output_data_size, 0); } @@ -246,7 +249,7 @@ gnutls_openpgp_crt_get_fingerprint (gnutls_openpgp_crt_t key, pk = pkt->pkt.public_key; *fprlen = 20; - + /* FIXME: Check if the draft allows old PGP keys. */ if (is_RSA (pk->pubkey_algo) && pk->version < 4) *fprlen = 16; @@ -267,7 +270,7 @@ _gnutls_openpgp_count_key_names (gnutls_openpgp_crt_t key) gnutls_assert (); return 0; } - + ctx = NULL; nuids = 0; while ((p = cdk_kbnode_walk (key->knode, &ctx, 0))) @@ -291,9 +294,9 @@ _gnutls_openpgp_count_key_names (gnutls_openpgp_crt_t key) * * Extracts the userID from the parsed OpenPGP key. * - * Returns 0 on success, and GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE - * if the index of the ID does not exist. - * + * Returns: %GNUTLS_E_SUCCESS on success, and if the index of the ID + * does not exist %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE, or an + * error code. **/ int gnutls_openpgp_crt_get_name (gnutls_openpgp_crt_t key, @@ -330,7 +333,7 @@ gnutls_openpgp_crt_get_name (gnutls_openpgp_crt_t key, { gnutls_assert (); return GNUTLS_E_INTERNAL_ERROR; - } + } uid = pkt->pkt.user_id; if (uid->len >= *sizeof_buf) @@ -351,21 +354,20 @@ gnutls_openpgp_crt_get_name (gnutls_openpgp_crt_t key, } /** - * gnutls_openpgp_crt_get_pk_algorithm - This function returns the key's PublicKey algorithm - * @key: is an OpenPGP key - * @bits: if bits is non null it will hold the size of the parameters' in bits - * - * This function will return the public key algorithm of an OpenPGP - * certificate. - * - * If bits is non null, it should have enough size to hold the parameters - * size in bits. For RSA the bits returned is the modulus. - * For DSA the bits returned are of the public exponent. - * - * Returns a member of the GNUTLS_PKAlgorithm enumeration on success, - * or a negative value on error. - * - **/ + * gnutls_openpgp_crt_get_pk_algorithm - return the key's PublicKey algorithm + * @key: is an OpenPGP key + * @bits: if bits is non null it will hold the size of the parameters' in bits + * + * This function will return the public key algorithm of an OpenPGP + * certificate. + * + * If bits is non null, it should have enough size to hold the parameters + * size in bits. For RSA the bits returned is the modulus. + * For DSA the bits returned are of the public exponent. + * + * Returns: a member of the #gnutls_pk_algorithm_t enumeration on + * success, or a negative value on error. + **/ gnutls_pk_algorithm_t gnutls_openpgp_crt_get_pk_algorithm (gnutls_openpgp_crt_t key, unsigned int *bits) @@ -377,7 +379,7 @@ gnutls_openpgp_crt_get_pk_algorithm (gnutls_openpgp_crt_t key, { gnutls_assert(); return GNUTLS_PK_UNKNOWN; - } + } algo = 0; pkt = cdk_kbnode_find_packet (key->knode, CDK_PKT_PUBLIC_KEY); @@ -387,7 +389,7 @@ gnutls_openpgp_crt_get_pk_algorithm (gnutls_openpgp_crt_t key, *bits = cdk_pk_get_nbits (pkt->pkt.public_key); algo = _gnutls_openpgp_get_algo(pkt->pkt.public_key->pubkey_algo); } - + return algo; } @@ -397,6 +399,8 @@ gnutls_openpgp_crt_get_pk_algorithm (gnutls_openpgp_crt_t key, * @key: the structure that contains the OpenPGP public key. * * Extract the version of the OpenPGP key. + * + * Returns: the version number is returned, or a negative value on errors. **/ int gnutls_openpgp_crt_get_version (gnutls_openpgp_crt_t key) @@ -533,17 +537,16 @@ gnutls_openpgp_crt_get_revoked_status (gnutls_openpgp_crt_t key) } /** - * gnutls_openpgp_crt_check_hostname - This function compares the given hostname with the hostname in the key - * @key: should contain an gnutls_openpgp_crt_t structure - * @hostname: A null terminated string that contains a DNS name - * - * This function will check if the given key's owner matches - * the given hostname. This is a basic implementation of the matching - * described in RFC2818 (HTTPS), which takes into account wildcards. - * - * Returns non zero on success, and zero on failure. - * - **/ + * gnutls_openpgp_crt_check_hostname - compare hostname with the key's hostname + * @key: should contain an #gnutls_openpgp_crt_t structure + * @hostname: A null terminated string that contains a DNS name + * + * This function will check if the given key's owner matches the + * given hostname. This is a basic implementation of the matching + * described in RFC2818 (HTTPS), which takes into account wildcards. + * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. + **/ int gnutls_openpgp_crt_check_hostname (gnutls_openpgp_crt_t key, const char *hostname) @@ -595,10 +598,9 @@ unsigned int usage = 0; * * This function will return certificate's key usage, by checking the * key algorithm. The key usage value will ORed values of the: - * GNUTLS_KEY_DIGITAL_SIGNATURE, GNUTLS_KEY_KEY_ENCIPHERMENT. - * - * A negative value may be returned in case of parsing error. + * %GNUTLS_KEY_DIGITAL_SIGNATURE, %GNUTLS_KEY_KEY_ENCIPHERMENT. * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. */ int gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t key, @@ -622,15 +624,14 @@ gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t key, } /** - * gnutls_openpgp_crt_get_subkey_count - This function returns the number of subkeys - * @key: is an OpenPGP key - * - * This function will return the number of subkeys present in the given - * OpenPGP certificate. - * - * Returns then number of subkeys or a negative value on error. - * - **/ + * gnutls_openpgp_crt_get_subkey_count - return the number of subkeys + * @key: is an OpenPGP key + * + * This function will return the number of subkeys present in the + * given OpenPGP certificate. + * + * Returns: the number of subkeys, or a negative value on error. + **/ int gnutls_openpgp_crt_get_subkey_count (gnutls_openpgp_crt_t key) { @@ -643,7 +644,7 @@ gnutls_openpgp_crt_get_subkey_count (gnutls_openpgp_crt_t key) gnutls_assert (); return 0; } - + ctx = NULL; subkeys = 0; while ((p = cdk_kbnode_walk (key->knode, &ctx, 0))) @@ -788,22 +789,21 @@ gnutls_openpgp_crt_get_subkey_revoked_status (gnutls_openpgp_crt_t key, } /** - * gnutls_openpgp_crt_get_subkey_pk_algorithm - This function returns the subkey's PublicKey algorithm - * @key: is an OpenPGP key - * @idx: is the subkey index - * @bits: if bits is non null it will hold the size of the parameters' in bits - * - * This function will return the public key algorithm of a subkey of an OpenPGP - * certificate. - * - * If bits is non null, it should have enough size to hold the parameters - * size in bits. For RSA the bits returned is the modulus. - * For DSA the bits returned are of the public exponent. - * - * Returns a member of the gnutls_pk_algorithm_t enumeration on success, - * or a negative value on error. - * - **/ + * gnutls_openpgp_crt_get_subkey_pk_algorithm - return the subkey's PublicKey algorithm + * @key: is an OpenPGP key + * @idx: is the subkey index + * @bits: if bits is non null it will hold the size of the parameters' in bits + * + * This function will return the public key algorithm of a subkey of an OpenPGP + * certificate. + * + * If bits is non null, it should have enough size to hold the + * parameters size in bits. For RSA the bits returned is the modulus. + * For DSA the bits returned are of the public exponent. + * + * Returns: a member of the #gnutls_pk_algorithm_t enumeration on + * success, or a negative value on error. + **/ gnutls_pk_algorithm_t gnutls_openpgp_crt_get_subkey_pk_algorithm (gnutls_openpgp_crt_t key, unsigned int idx, unsigned int *bits) @@ -816,7 +816,7 @@ gnutls_openpgp_crt_get_subkey_pk_algorithm (gnutls_openpgp_crt_t key, gnutls_assert(); return GNUTLS_PK_UNKNOWN; } - + pkt = _get_public_subkey( key, idx); algo = 0; @@ -826,7 +826,7 @@ gnutls_openpgp_crt_get_subkey_pk_algorithm (gnutls_openpgp_crt_t key, *bits = cdk_pk_get_nbits (pkt->pkt.public_key); algo = _gnutls_openpgp_get_algo(pkt->pkt.public_key->pubkey_algo); } - + return algo; } @@ -1290,17 +1290,17 @@ cleanup: /** - * gnutls_openpgp_crt_get_pk_rsa_raw - This function will export the RSA public key - * @crt: Holds the certificate - * @m: will hold the modulus - * @e: will hold the public exponent - * - * This function will export the RSA public key's parameters found in - * the given structure. The new parameters will be allocated using - * gnutls_malloc() and will be stored in the appropriate datum. - * - * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. - **/ + * gnutls_openpgp_crt_get_pk_rsa_raw - export the RSA public key + * @crt: Holds the certificate + * @m: will hold the modulus + * @e: will hold the public exponent + * + * This function will export the RSA public key's parameters found in + * the given structure. The new parameters will be allocated using + * gnutls_malloc() and will be stored in the appropriate datum. + * + * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. + **/ int gnutls_openpgp_crt_get_pk_rsa_raw (gnutls_openpgp_crt_t crt, gnutls_datum_t * m, gnutls_datum_t * e) @@ -1319,19 +1319,19 @@ int ret; } /** - * gnutls_openpgp_crt_get_pk_dsa_raw - This function will export the DSA public key - * @crt: Holds the certificate - * @p: will hold the p - * @q: will hold the q - * @g: will hold the g - * @y: will hold the y - * - * This function will export the DSA public key's parameters found in - * the given certificate. The new parameters will be allocated using - * gnutls_malloc() and will be stored in the appropriate datum. - * - * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. - **/ + * gnutls_openpgp_crt_get_pk_dsa_raw - export the DSA public key + * @crt: Holds the certificate + * @p: will hold the p + * @q: will hold the q + * @g: will hold the g + * @y: will hold the y + * + * This function will export the DSA public key's parameters found in + * the given certificate. The new parameters will be allocated using + * gnutls_malloc() and will be stored in the appropriate datum. + * + * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. + **/ int gnutls_openpgp_crt_get_pk_dsa_raw (gnutls_openpgp_crt_t crt, gnutls_datum_t * p, gnutls_datum_t * q, @@ -1346,23 +1346,23 @@ int ret; gnutls_assert (); return ret; } - + return _get_pk_dsa_raw( crt, keyid, p, q, g, y); } /** - * gnutls_openpgp_crt_get_subkey_pk_rsa_raw - This function will export the RSA public key - * @crt: Holds the certificate - * @idx: Is the subkey index - * @m: will hold the modulus - * @e: will hold the public exponent - * - * This function will export the RSA public key's parameters found in - * the given structure. The new parameters will be allocated using - * gnutls_malloc() and will be stored in the appropriate datum. - * - * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. - **/ + * gnutls_openpgp_crt_get_subkey_pk_rsa_raw - export the RSA public key + * @crt: Holds the certificate + * @idx: Is the subkey index + * @m: will hold the modulus + * @e: will hold the public exponent + * + * This function will export the RSA public key's parameters found in + * the given structure. The new parameters will be allocated using + * gnutls_malloc() and will be stored in the appropriate datum. + * + * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. + **/ int gnutls_openpgp_crt_get_subkey_pk_rsa_raw (gnutls_openpgp_crt_t crt, unsigned int idx, gnutls_datum_t * m, gnutls_datum_t * e) @@ -1376,40 +1376,43 @@ int ret; gnutls_assert (); return ret; } - + return _get_pk_rsa_raw( crt, keyid, m, e); } /** - * gnutls_openpgp_crt_get_subkey_pk_dsa_raw - This function will export the DSA public key - * @crt: Holds the certificate - * @idx: Is the subkey index - * @p: will hold the p - * @q: will hold the q - * @g: will hold the g - * @y: will hold the y - * - * This function will export the DSA public key's parameters found in - * the given certificate. The new parameters will be allocated using - * gnutls_malloc() and will be stored in the appropriate datum. - * - * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. - **/ + * gnutls_openpgp_crt_get_subkey_pk_dsa_raw - export the DSA public key + * @crt: Holds the certificate + * @idx: Is the subkey index + * @p: will hold the p + * @q: will hold the q + * @g: will hold the g + * @y: will hold the y + * + * This function will export the DSA public key's parameters found in + * the given certificate. The new parameters will be allocated using + * gnutls_malloc() and will be stored in the appropriate datum. + * + * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. + **/ int -gnutls_openpgp_crt_get_subkey_pk_dsa_raw (gnutls_openpgp_crt_t crt, unsigned int idx, - gnutls_datum_t * p, gnutls_datum_t * q, - gnutls_datum_t * g, gnutls_datum_t * y) +gnutls_openpgp_crt_get_subkey_pk_dsa_raw (gnutls_openpgp_crt_t crt, + unsigned int idx, + gnutls_datum_t * p, + gnutls_datum_t * q, + gnutls_datum_t * g, + gnutls_datum_t * y) { -gnutls_openpgp_keyid_t keyid; -int ret; + gnutls_openpgp_keyid_t keyid; + int ret; - ret = gnutls_openpgp_crt_get_subkey_id( crt, idx, keyid); + ret = gnutls_openpgp_crt_get_subkey_id( crt, idx, keyid); if (ret < 0) { gnutls_assert (); return ret; } - + return _get_pk_dsa_raw( crt, keyid, p, q, g, y); } @@ -1448,7 +1451,8 @@ gnutls_openpgp_crt_get_preferred_key_id (gnutls_openpgp_crt_t key, * **/ int -gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t key, const gnutls_openpgp_keyid_t keyid) +gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t key, + const gnutls_openpgp_keyid_t keyid) { int ret; @@ -1479,13 +1483,16 @@ int ret; * @keyid: the struct to save the keyid. * @flag: Non zero indicates that a valid subkey is always returned. * - * Returns the 64-bit keyID of the first valid OpenPGP subkey marked for authentication. - * If flag is non zero and no authentication subkey exists, then a valid subkey will - * be returned even if it is not marked for authentication. - * - * Returns zero on success. + * Returns the 64-bit keyID of the first valid OpenPGP subkey marked + * for authentication. If flag is non zero and no authentication + * subkey exists, then a valid subkey will be returned even if it is + * not marked for authentication. + * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ -int gnutls_openpgp_crt_get_auth_subkey( gnutls_openpgp_crt_t crt, gnutls_openpgp_keyid_t keyid, unsigned int flag) +int gnutls_openpgp_crt_get_auth_subkey( gnutls_openpgp_crt_t crt, + gnutls_openpgp_keyid_t keyid, + unsigned int flag) { int ret, subkeys, i; unsigned int usage; @@ -1506,38 +1513,38 @@ int gnutls_openpgp_crt_get_auth_subkey( gnutls_openpgp_crt_t crt, gnutls_openpgp ret = gnutls_openpgp_crt_get_subkey_revoked_status(crt, i); if (ret != 0) /* it is revoked. ignore it */ - continue; + continue; if (keyid_init == 0) - { /* keep the first valid subkey */ - ret = gnutls_openpgp_crt_get_subkey_id( crt, i, keyid); - if (ret < 0) - { - gnutls_assert(); - return ret; - } - - keyid_init = 1; - } - + { /* keep the first valid subkey */ + ret = gnutls_openpgp_crt_get_subkey_id( crt, i, keyid); + if (ret < 0) + { + gnutls_assert(); + return ret; + } + + keyid_init = 1; + } + ret = gnutls_openpgp_crt_get_subkey_usage( crt, i, &usage); if (ret < 0) - { - gnutls_assert(); - return ret; - } + { + gnutls_assert(); + return ret; + } if (usage & GNUTLS_KEY_KEY_AGREEMENT) - { - ret = gnutls_openpgp_crt_get_subkey_id( crt, i, keyid); - if (ret < 0) - { - gnutls_assert(); - return ret; - } - - return 0; - } + { + ret = gnutls_openpgp_crt_get_subkey_id( crt, i, keyid); + if (ret < 0) + { + gnutls_assert(); + return ret; + } + + return 0; + } } if (flag && keyid_init) return 0; diff --git a/lib/openpgp/pgpverify.c b/lib/openpgp/pgpverify.c index 34d15fb99c..6659a6f911 100644 --- a/lib/openpgp/pgpverify.c +++ b/lib/openpgp/pgpverify.c @@ -31,7 +31,6 @@ #include <gnutls_openpgp.h> #include <gnutls_num.h> - /** * gnutls_openpgp_crt_verify_ring - Verify all signatures in the key * @key: the structure that holds the key. @@ -39,20 +38,22 @@ * @flags: unused (should be 0) * @verify: will hold the certificate verification output. * - * Verify all signatures in the key, using the given set of keys (keyring). + * Verify all signatures in the key, using the given set of keys + * (keyring). * - * The key verification output will be put in @verify and will be - * one or more of the gnutls_certificate_status_t enumerated elements bitwise or'd. + * The key verification output will be put in @verify and will be one + * or more of the #gnutls_certificate_status_t enumerated elements + * bitwise or'd. * - * GNUTLS_CERT_INVALID: A signature on the key is invalid. + * %GNUTLS_CERT_INVALID: A signature on the key is invalid. * - * GNUTLS_CERT_REVOKED: The key has been revoked. + * %GNUTLS_CERT_REVOKED: The key has been revoked. * - * Note that this function does not verify using any "web of - * trust". You may use GnuPG for that purpose, or any other external - * PGP application. + * Note that this function does not verify using any "web of trust". + * You may use GnuPG for that purpose, or any other external PGP + * application. * - * Returns 0 on success. + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t key, @@ -70,7 +71,7 @@ gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t key, } *verify = 0; - + rc = cdk_pk_check_sigs (key->knode, keyring->db, &status); if (rc == CDK_Error_No_Key) { @@ -109,7 +110,7 @@ gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t key, if (rc == 0 && *verify & GNUTLS_CERT_SIGNER_NOT_FOUND) *verify ^= GNUTLS_CERT_SIGNER_NOT_FOUND; } - + return 0; } @@ -120,13 +121,13 @@ gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t key, * @flags: unused (should be 0) * @verify: will hold the key verification output. * - * Verifies the self signature in the key. - * The key verification output will be put in @verify and will be - * one or more of the gnutls_certificate_status_t enumerated elements bitwise or'd. + * Verifies the self signature in the key. The key verification + * output will be put in @verify and will be one or more of the + * gnutls_certificate_status_t enumerated elements bitwise or'd. * - * GNUTLS_CERT_INVALID: The self signature on the key is invalid. + * %GNUTLS_CERT_INVALID: The self signature on the key is invalid. * - * Returns 0 on success. + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_openpgp_crt_verify_self (gnutls_openpgp_crt_t key, diff --git a/lib/openpgp/privkey.c b/lib/openpgp/privkey.c index 695346b25e..49208ff22d 100644 --- a/lib/openpgp/privkey.c +++ b/lib/openpgp/privkey.c @@ -40,7 +40,7 @@ * * This function will initialize an OpenPGP key structure. * - * Returns 0 on success. + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_openpgp_privkey_init (gnutls_openpgp_privkey_t * key) @@ -85,7 +85,7 @@ gnutls_openpgp_privkey_deinit (gnutls_openpgp_privkey_t key) * the native gnutls_openpgp_privkey_t format. The output will be * stored in 'key'. * - * Returns 0 on success. + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_openpgp_privkey_import (gnutls_openpgp_privkey_t key, @@ -139,21 +139,21 @@ gnutls_openpgp_privkey_import (gnutls_openpgp_privkey_t key, } /** - * gnutls_openpgp_privkey_export - This function will export a RAW or BASE64 encoded key - * @key: Holds the key. - * @format: One of gnutls_openpgp_crt_fmt_t elements. - * @password: the password that will be used to encrypt the key. - * @flags: zero for future compatibility - * @output_data: will contain the key base64 encoded or raw - * @output_data_size: holds the size of output_data (and will be replaced by the actual size of parameters) - * - * This function will convert the given key to RAW or Base64 format. - * If the buffer provided is not long enough to hold the output, then - * GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. - * - * Returns 0 on success. - * - **/ + * gnutls_openpgp_privkey_export - export a RAW or BASE64 encoded key + * @key: Holds the key. + * @format: One of gnutls_openpgp_crt_fmt_t elements. + * @password: the password that will be used to encrypt the key. + * @flags: zero for future compatibility + * @output_data: will contain the key base64 encoded or raw + * @output_data_size: holds the size of output_data (and will be + * replaced by the actual size of parameters) + * + * This function will convert the given key to RAW or Base64 format. + * If the buffer provided is not long enough to hold the output, then + * GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. + * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. + **/ int gnutls_openpgp_privkey_export (gnutls_openpgp_privkey_t key, gnutls_openpgp_crt_fmt_t format, @@ -166,7 +166,7 @@ gnutls_openpgp_privkey_export (gnutls_openpgp_privkey_t key, /** - * gnutls_openpgp_privkey_get_pk_algorithm - This function returns the key's PublicKey algorithm + * gnutls_openpgp_privkey_get_pk_algorithm - return the key's PublicKey algorithm * @key: is an OpenPGP key * @bits: if bits is non null it will hold the size of the parameters' in bits * @@ -174,12 +174,11 @@ gnutls_openpgp_privkey_export (gnutls_openpgp_privkey_t key, * certificate. * * If bits is non null, it should have enough size to hold the parameters - * size in bits. For RSA the bits returned is the modulus. + * size in bits. For RSA the bits returned is the modulus. * For DSA the bits returned are of the public exponent. * - * Returns a member of the GNUTLS_PKAlgorithm enumeration on success, - * or a negative value on error. - * + * Returns: a member of the #gnutls_pk_algorithm_t enumeration on + * success, or a negative value on error. **/ gnutls_pk_algorithm_t gnutls_openpgp_privkey_get_pk_algorithm (gnutls_openpgp_privkey_t key, @@ -230,7 +229,6 @@ int algo; * * Returns: true (1) if the key has been revoked, or false (0) if it * has not, or a negative value indicates an error. - * **/ int gnutls_openpgp_privkey_get_revoked_status (gnutls_openpgp_privkey_t key) @@ -412,22 +410,21 @@ gnutls_openpgp_privkey_get_subkey_revoked_status (gnutls_openpgp_privkey_t key, } /** - * gnutls_openpgp_privkey_get_subkey_pk_algorithm - This function returns the subkey's PublicKey algorithm - * @key: is an OpenPGP key - * @idx: is the subkey index - * @bits: if bits is non null it will hold the size of the parameters' in bits - * - * This function will return the public key algorithm of a subkey of an OpenPGP - * certificate. - * - * If bits is non null, it should have enough size to hold the parameters - * size in bits. For RSA the bits returned is the modulus. - * For DSA the bits returned are of the public exponent. - * - * Returns a member of the gnutls_pk_algorithm_t enumeration on success, - * or a negative value on error. - * - **/ + * gnutls_openpgp_privkey_get_subkey_pk_algorithm - return the subkey's PublicKey algorithm + * @key: is an OpenPGP key + * @idx: is the subkey index + * @bits: if bits is non null it will hold the size of the parameters' in bits + * + * This function will return the public key algorithm of a subkey of an OpenPGP + * certificate. + * + * If bits is non null, it should have enough size to hold the parameters + * size in bits. For RSA the bits returned is the modulus. + * For DSA the bits returned are of the public exponent. + * + * Returns: a member of the #gnutls_pk_algorithm_t enumeration on + * success, or a negative value on error. + **/ gnutls_pk_algorithm_t gnutls_openpgp_privkey_get_subkey_pk_algorithm (gnutls_openpgp_privkey_t key, unsigned int idx, unsigned int *bits) @@ -868,21 +865,21 @@ cleanup: /** - * gnutls_openpgp_privkey_export_rsa_raw - This function will export the RSA private key - * @pkey: Holds the certificate - * @m: will hold the modulus - * @e: will hold the public exponent - * @d: will hold the private exponent - * @p: will hold the first prime (p) - * @q: will hold the second prime (q) - * @u: will hold the coefficient - * - * This function will export the RSA private key's parameters found in - * the given structure. The new parameters will be allocated using - * gnutls_malloc() and will be stored in the appropriate datum. - * - * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. - **/ + * gnutls_openpgp_privkey_export_rsa_raw - This function will export the RSA private key + * @pkey: Holds the certificate + * @m: will hold the modulus + * @e: will hold the public exponent + * @d: will hold the private exponent + * @p: will hold the first prime (p) + * @q: will hold the second prime (q) + * @u: will hold the coefficient + * + * This function will export the RSA private key's parameters found in + * the given structure. The new parameters will be allocated using + * gnutls_malloc() and will be stored in the appropriate datum. + * + * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. + **/ int gnutls_openpgp_privkey_export_rsa_raw (gnutls_openpgp_privkey_t pkey, gnutls_datum_t * m, gnutls_datum_t * e, @@ -903,20 +900,20 @@ int ret; } /** - * gnutls_openpgp_privkey_export_dsa_raw - This function will export the DSA private key - * @pkey: Holds the certificate - * @p: will hold the p - * @q: will hold the q - * @g: will hold the g - * @y: will hold the y - * @x: will hold the x - * - * This function will export the DSA private key's parameters found in - * the given certificate. The new parameters will be allocated using - * gnutls_malloc() and will be stored in the appropriate datum. - * - * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. - **/ + * gnutls_openpgp_privkey_export_dsa_raw - This function will export the DSA private key + * @pkey: Holds the certificate + * @p: will hold the p + * @q: will hold the q + * @g: will hold the g + * @y: will hold the y + * @x: will hold the x + * + * This function will export the DSA private key's parameters found in + * the given certificate. The new parameters will be allocated using + * gnutls_malloc() and will be stored in the appropriate datum. + * + * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. + **/ int gnutls_openpgp_privkey_export_dsa_raw (gnutls_openpgp_privkey_t pkey, gnutls_datum_t * p, gnutls_datum_t * q, @@ -937,22 +934,22 @@ int ret; } /** - * gnutls_openpgp_privkey_export_subkey_rsa_raw - This function will export the RSA private key - * @pkey: Holds the certificate - * @idx: Is the subkey index - * @m: will hold the modulus - * @e: will hold the public exponent - * @d: will hold the private exponent - * @p: will hold the first prime (p) - * @q: will hold the second prime (q) - * @u: will hold the coefficient - * - * This function will export the RSA private key's parameters found in - * the given structure. The new parameters will be allocated using - * gnutls_malloc() and will be stored in the appropriate datum. - * - * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. - **/ + * gnutls_openpgp_privkey_export_subkey_rsa_raw - export the RSA private key + * @pkey: Holds the certificate + * @idx: Is the subkey index + * @m: will hold the modulus + * @e: will hold the public exponent + * @d: will hold the private exponent + * @p: will hold the first prime (p) + * @q: will hold the second prime (q) + * @u: will hold the coefficient + * + * This function will export the RSA private key's parameters found in + * the given structure. The new parameters will be allocated using + * gnutls_malloc() and will be stored in the appropriate datum. + * + * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. + **/ int gnutls_openpgp_privkey_export_subkey_rsa_raw (gnutls_openpgp_privkey_t pkey, unsigned int idx, gnutls_datum_t * m, gnutls_datum_t * e, @@ -973,21 +970,21 @@ int ret; } /** - * gnutls_openpgp_privkey_export_subkey_dsa_raw - export the DSA private key - * @pkey: Holds the certificate - * @idx: Is the subkey index - * @p: will hold the p - * @q: will hold the q - * @g: will hold the g - * @y: will hold the y - * @x: will hold the x - * - * This function will export the DSA private key's parameters found - * in the given certificate. The new parameters will be allocated - * using gnutls_malloc() and will be stored in the appropriate datum. - * - * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. - **/ + * gnutls_openpgp_privkey_export_subkey_dsa_raw - export the DSA private key + * @pkey: Holds the certificate + * @idx: Is the subkey index + * @p: will hold the p + * @q: will hold the q + * @g: will hold the g + * @y: will hold the y + * @x: will hold the x + * + * This function will export the DSA private key's parameters found + * in the given certificate. The new parameters will be allocated + * using gnutls_malloc() and will be stored in the appropriate datum. + * + * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error. + **/ int gnutls_openpgp_privkey_export_subkey_dsa_raw (gnutls_openpgp_privkey_t pkey, unsigned int idx, diff --git a/lib/x509/rfc2818_hostname.c b/lib/x509/rfc2818_hostname.c index eeac3454f8..ca066cd737 100644 --- a/lib/x509/rfc2818_hostname.c +++ b/lib/x509/rfc2818_hostname.c @@ -28,18 +28,17 @@ #include <gnutls_errors.h> /** - * gnutls_x509_crt_check_hostname - This function compares the given hostname with the hostname in the certificate - * @cert: should contain an gnutls_x509_crt_t structure - * @hostname: A null terminated string that contains a DNS name - * - * This function will check if the given certificate's subject - * matches the given hostname. This is a basic implementation of the - * matching described in RFC2818 (HTTPS), which takes into account - * wildcards, and the DNSName/IPAddress subject alternative name PKIX - * extension. - * - * Returns non zero for a successful match, and zero on failure. - **/ + * gnutls_x509_crt_check_hostname - compares the hostname with certificate's hostname + * @cert: should contain an gnutls_x509_crt_t structure + * @hostname: A null terminated string that contains a DNS name + * + * This function will check if the given certificate's subject matches + * the given hostname. This is a basic implementation of the matching + * described in RFC2818 (HTTPS), which takes into account wildcards, + * and the DNSName/IPAddress subject alternative name PKIX extension. + * + * Returns: non zero for a successful match, and zero on failure. + **/ int gnutls_x509_crt_check_hostname (gnutls_x509_crt_t cert, const char *hostname) { |