From: Nikos Mavrogiannopoulos Date: Mon, 8 Apr 2013 15:28:09 +0000 (+0200) Subject: doc updates X-Git-Tag: gnutls_3_2_0~68 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8ea64ed94225a2abc12fbb133b379728858a57c4;p=thirdparty%2Fgnutls.git doc updates --- diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi index c0caf639ec..d66558ea44 100644 --- a/doc/cha-cert-auth2.texi +++ b/doc/cha-cert-auth2.texi @@ -323,9 +323,12 @@ well as a trusted CA certificate. Generic and higher level private key import functions are available, that import plain or encrypted keys and will auto-detect the encrypted key format. +@showfuncdesc{gnutls_privkey_import_x509_raw} + @showfuncdesc{gnutls_x509_privkey_import2} -@showfuncdesc{gnutls_privkey_import_x509_raw} +Any keys imported using those functions can be imported to a certificate +credentials structure using @funcref{gnutls_certificate_set_key}. @subsubheading @acronym{PKCS} #8 structures @cindex PKCS #8 @@ -346,7 +349,9 @@ be decrypted. A @acronym{PKCS} #12 structure @xcite{PKCS12} usually contains a user's private keys and certificates. It is commonly used in browsers to -export and import the user's identities. +export and import the user's identities. A file containing such a key can +be directly imported to a certificate credentials structure by using +@funcref{gnutls_certificate_set_x509_simple_pkcs12_file}. In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled using the @code{gnutls_pkcs12_t} type. This is an abstract type that @@ -366,13 +371,11 @@ functions below. @showfuncC{gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name} The functions below are used to generate a PKCS #12 structure. An example -of their usage is also shown. +of their usage is shown at @ref{PKCS #12 structure generation example}. @showfuncC{gnutls_pkcs12_set_bag,gnutls_pkcs12_bag_encrypt,gnutls_pkcs12_generate_mac} @showfuncE{gnutls_pkcs12_bag_set_data,gnutls_pkcs12_bag_set_crl,gnutls_pkcs12_bag_set_crt,gnutls_pkcs12_bag_set_key_id,gnutls_pkcs12_bag_set_friendly_name} -@verbatiminclude examples/ex-pkcs12.c - @subsubheading OpenSSL encrypted keys @cindex OpenSSL encrypted keys Unfortunately the structures discussed in the previous sections are diff --git a/doc/cha-gtls-examples.texi b/doc/cha-gtls-examples.texi index 7233cc004c..23a488e2fd 100644 --- a/doc/cha-gtls-examples.texi +++ b/doc/cha-gtls-examples.texi @@ -253,6 +253,7 @@ A small tool to generate OCSP requests. * Checking for an alert:: * X.509 certificate parsing example:: * Listing the ciphersuites in a priority string:: +* PKCS #12 structure generation example:: @end menu @node Checking for an alert @@ -281,6 +282,14 @@ priority string. @verbatiminclude examples/print-ciphersuites.c +@node PKCS #12 structure generation example +@subsection PKCS #12 structure generation example + +This small program demonstrates the usage of the PKCS #12 API, by generating +such a structure. + +@verbatiminclude examples/ex-pkcs12.c + @node XSSL examples @section XSSL examples diff --git a/lib/gnutls_privkey.c b/lib/gnutls_privkey.c index 8e4965e352..f2d79d945b 100644 --- a/lib/gnutls_privkey.c +++ b/lib/gnutls_privkey.c @@ -920,7 +920,7 @@ gnutls_privkey_decrypt_data (gnutls_privkey_t key, * This function will import the given private key to the abstract * #gnutls_privkey_t structure. * - * The supported formats are basic unencrypted key, PKCS #8, PKCS #12, + * The supported formats are basic unencrypted key, PKCS8, PKCS12, * and the openssl format. * * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a diff --git a/lib/x509/pkcs12.c b/lib/x509/pkcs12.c index 448b1658fc..11eee4813b 100644 --- a/lib/x509/pkcs12.c +++ b/lib/x509/pkcs12.c @@ -1383,19 +1383,19 @@ skip: /** * gnutls_pkcs12_simple_parse: - * @p12: the PKCS#12 blob. - * @password: optional password used to decrypt PKCS#12 blob, bags and keys. + * @p12: the PKCS12 blob. + * @password: optional password used to decrypt PKCS12 blob, bags and keys. * @key: a structure to store the parsed private key. * @chain: the corresponding to key certificate chain (may be %NULL) * @chain_len: will be updated with the number of additional (may be %NULL) * @extra_certs: optional pointer to receive an array of additional - * certificates found in the PKCS#12 blob (may be %NULL). + * certificates found in the PKCS12 blob (may be %NULL). * @extra_certs_len: will be updated with the number of additional * certs (may be %NULL). * @crl: an optional structure to store the parsed CRL (may be %NULL). * @flags: should be zero or one of GNUTLS_PKCS12_SP_* * - * This function parses a PKCS#12 blob in @p12blob and extracts the + * This function parses a PKCS12 blob in @p12blob and extracts the * private key, the corresponding certificate chain, and any additional * certificates and a CRL. * @@ -1403,13 +1403,13 @@ skip: * and both may be set to %NULL. If either is non-%NULL, then both must * be set. * - * Encrypted PKCS#12 bags and PKCS#8 private keys are supported. However, + * Encrypted PKCS12 bags and PKCS8 private keys are supported. However, * only password based security, and the same password for all * operations, are supported. * - * A PKCS#12 file may contain many keys and/or certificates, and there + * A PKCS12 file may contain many keys and/or certificates, and there * is no way to identify which key/certificate pair you want. You - * should make sure the PKCS#12 file only contain one key/certificate + * should make sure the PKCS12 file only contain one key/certificate * pair and/or one CRL. * * It is believed that the limitations of this function are acceptable diff --git a/lib/x509/privkey.c b/lib/x509/privkey.c index 34cee63900..5fd60d7b85 100644 --- a/lib/x509/privkey.c +++ b/lib/x509/privkey.c @@ -609,7 +609,7 @@ fail: * the native #gnutls_x509_privkey_t format, irrespective of the * input format. The input format is auto-detected. * - * The supported formats are basic unencrypted key, PKCS #8, PKCS #12, + * The supported formats are basic unencrypted key, PKCS8, PKCS12, * and the openssl format. * * If the provided key is encrypted but no password was given, then