[SCM] GNU gnutls branch, master, updated. gnutls_3_1_4-21-g96c38a6

[Nikos Mavrogiannopoulos]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU gnutls".

http://git.savannah.gnu.org/cgit/gnutls.git/commit/?id=96c38a6c89fe0b6f7d826c3588479ec861811054

The branch, master has been updated
       via  96c38a6c89fe0b6f7d826c3588479ec861811054 (commit)
      from  f8a0214756de685fe7c7cae31be9335531812d6a (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 96c38a6c89fe0b6f7d826c3588479ec861811054
Author: Nikos Mavrogiannopoulos <address@hidden>
Date:   Sat Nov 17 16:49:15 2012 +0100

    doc updates

-----------------------------------------------------------------------

Summary of changes:
 doc/Makefile.am         |    2 +-
 doc/cha-cert-auth2.texi |   34 ++++---
 doc/cha-crypto.texi     |   54 ++++++++++
 doc/cha-gtls-app.texi   |  260 +++++++++++++++++++----------------------------
 doc/gnutls.texi         |    3 +
 lib/x509/privkey.c      |    2 +-
 6 files changed, 181 insertions(+), 174 deletions(-)
 create mode 100644 doc/cha-crypto.texi

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 85f892f..bb2624f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -140,7 +140,7 @@ gnutls_TEXINFOS = gnutls.texi fdl-1.3.texi                  
        \
        cha-library.texi cha-preface.texi cha-programs.texi             \
        sec-tls-app.texi cha-errors.texi cha-support.texi               \
        cha-shared-key.texi cha-gtls-examples.texi cha-upgrade.texi     \
-       cha-tokens.texi
+       cha-tokens.texi cha-crypto.texi
 
 gnutls_TEXINFOS += invoke-gnutls-cli.texi invoke-gnutls-cli-debug.texi \
        invoke-gnutls-serv.texi invoke-certtool.texi invoke-srptool.texi \
diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi
index 088ec1b..a463d6d 100644
--- a/doc/cha-cert-auth2.texi
+++ b/doc/cha-cert-auth2.texi
@@ -306,20 +306,27 @@ whether the received OCSP response corresponds to the 
certificate being checked.
 @section Managing encrypted keys
 @cindex Encrypted keys
 
-Transferring or storing private keys in plain might not be a
-good idea. Any access on the keys becomes a fatal compromise.
+Transferring or storing private keys in plain may not be a
+good idea, since any compromise is irreparable.
 Storing the keys in hardware security modules (see @ref{Smart cards and HSMs})
 could solve the storage problem but it is not always practical
-or efficient enough. This section describes alternative ways
-that involve encryption of the private keys to store and
-transfer.
+or efficient enough. This section describes ways to store and
+transfer encrypted private keys.
 
-There are two alternatives to use for key encryption, 
-PKCS #8 and #12 methods of private key encryption. The PKCS #8
-method only allows encryption of the private key, whilst the
-PKCS #12 method allows in addition the bundling of other
-data into the structure. That could be bundling together the
-certificate as well as the trusted CA certificate.
+There are methods for key encryption, namely the
+PKCS #8, PKCS #12 and OpenSSL's custom encrypted private key formats. 
+The PKCS #8 and the OpenSSL's method allow encryption of the private key, 
+while the PKCS #12 method allows, in addition, the bundling of accompanying 
+data into the structure. That is typically the corresponding certificate, as 
+well as a trusted CA certificate.
+
address@hidden High level functionality
+Generic and higher level private key import functions are available, that
+will auto-detect the encrypted key format.
+
address@hidden
+
address@hidden
 
 @subheading @acronym{PKCS} #8 structures
 @cindex PKCS #8
@@ -367,7 +374,7 @@ of their usage is also shown.
 
 @verbatiminclude examples/ex-pkcs12.c
 
address@hidden Other structures
address@hidden OpenSSL encrypted keys
 @cindex OpenSSL encrypted keys
 Unfortunately the structures discussed in the previous sections are
 not the only structures that may hold an encrypted private key. For example
@@ -376,9 +383,6 @@ are also supported in GnuTLS with 
@funcref{gnutls_x509_privkey_import_openssl}.
 
 @showfuncdesc{gnutls_x509_privkey_import_openssl}
 
-Generic and higher level private key import functions are also available.
address@hidden,gnutls_privkey_import_x509_raw}
-
 @include invoke-certtool.texi
 
 @include invoke-ocsptool.texi
diff --git a/doc/cha-crypto.texi b/doc/cha-crypto.texi
new file mode 100644
index 0000000..956ca22
--- /dev/null
+++ b/doc/cha-crypto.texi
@@ -0,0 +1,54 @@
address@hidden Using GnuTLS as a cryptographic library
address@hidden Using GnuTLS as a cryptographic library
+
address@hidden is not a low-level cryptographic library, i.e., 
+it does not provide access to basic cryptographic primitives. However
+it abstracts the internal cryptographic back-end (see @ref{Cryptographic 
Backend}),
+providing symmetric crypto, hash and HMAC algorithms, as well access
+to the random number generation.
+
address@hidden
+* Symmetric cryptography::
+* Hash and HMAC functions::
+* Random number generation::
address@hidden menu
+
address@hidden Symmetric cryptography
address@hidden Symmetric cryptography
address@hidden symmetric cryptography
+
+The available functions to access symmetric crypto algorithms operations
+are shown below. The supported algorithms are the algorithms required by the 
TLS protocol.
+They are listed in @ref{tab:ciphers}.
+
address@hidden,gnutls_cipher_encrypt2,gnutls_cipher_decrypt2,gnutls_cipher_set_iv,gnutls_cipher_deinit}
+
+In order to support authenticated encryption with associated data (AEAD) 
algorithms the following
+functions are provided to set the associated data and retrieve the 
authentication tag.
+
address@hidden,gnutls_cipher_tag}
+
address@hidden Hash and HMAC functions
address@hidden Hash and HMAC functions
address@hidden hash functions
address@hidden HMAC functions
+
+The available operations to access hash functions and hash-MAC (HMAC) 
algorithms
+are shown below. HMAC algorithms provided keyed hash functionality. They 
supported HMAC algorithms are listed in @ref{tab:macs}.
+
address@hidden,gnutls_hmac,gnutls_hmac_output,gnutls_hmac_deinit,gnutls_hmac_get_len,gnutls_hmac_fast}
+
+The available functions to access hash functions are shown below. The 
supported hash functions
+are the same as the HMAC algorithms.
+
address@hidden,gnutls_hash,gnutls_hash_output,gnutls_hash_deinit,gnutls_hash_get_len,gnutls_hash_fast}
+
address@hidden Random number generation
address@hidden Random number generation
address@hidden random numbers
+
+Access to the random number generator is provided using the 
@funcref{gnutls_rnd}
+function. It allows obtaining random data of various levels.
+
address@hidden,The random number levels.}
address@hidden
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index b6ad475..d2f84fd 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -11,9 +11,8 @@
 * Data transfer and termination::
 * Handling alerts::
 * Priority Strings::
-* Advanced topics::
-* Using the cryptographic library::
 * Selecting cryptographic key sizes::
+* Advanced topics::
 @end menu
 
 @node Introduction to the library
@@ -1074,6 +1073,108 @@ except TLS 1.2:
     "SECURE128:+SECURE192:-VERS-TLS-ALL:+VERS-TLS1.2"
 @end example
 
address@hidden Selecting cryptographic key sizes
address@hidden Selecting cryptographic key sizes
address@hidden key sizes
+
+Because many algorithms are involved in TLS, it is not easy to set
+a consistent security level.  For this reason in @ref{tab:key-sizes} we
+present some correspondence between key sizes of symmetric algorithms
+and public key algorithms based on @xcite{ECRYPT}. 
+Those can be used to generate certificates with
+appropriate key sizes as well as select parameters for Diffie-Hellman and SRP
+authentication.
+
address@hidden Table,tab:key-sizes
address@hidden @columnfractions .10 .12 .10 .20 .32
+
address@hidden Security bits @tab RSA, DH and SRP parameter size @tab ECC key 
size @tab Security parameter @tab Description
+
address@hidden <72
address@hidden <1008
address@hidden <160
address@hidden @code{INSECURE}
address@hidden Considered to be insecure
+
address@hidden 72
address@hidden 1008
address@hidden 160
address@hidden @code{WEAK}
address@hidden Short term protection against small organizations
+
address@hidden 80
address@hidden 1248
address@hidden 160
address@hidden @code{LOW}
address@hidden Very short term protection against agencies
+
address@hidden 96
address@hidden 1776
address@hidden 192
address@hidden @code{LEGACY}
address@hidden Legacy standard level
+
address@hidden 112
address@hidden 2432
address@hidden 224
address@hidden @code{NORMAL}
address@hidden Medium-term protection
+
address@hidden 128
address@hidden 3248
address@hidden 256
address@hidden @code{HIGH}
address@hidden Long term protection
+
address@hidden 256
address@hidden 15424
address@hidden 512
address@hidden @code{ULTRA}
address@hidden Foreseeable future
+
address@hidden multitable
address@hidden sizes and security parameters.}
address@hidden float
+
+The first column  provides a security parameter in a number of bits. This
+gives an indication of the number of combinations to be tried by an adversary
+to brute force a key. For example to test all possible keys in a 112 bit 
security parameter
address@hidden combinations have to be tried. For today's technology this is 
infeasible.
+The next two columns correlate the security
+parameter with actual bit sizes of parameters for DH, RSA, SRP and ECC 
algorithms.
+A mapping to @code{gnutls_sec_param_t} value is given for each security 
parameter, on
+the next column, and finally a brief description of the level.
+
address@hidden @showenumdesc{gnutls_sec_param_t,The @address@hidden 
enumeration.}
+
+Note, however, that the values suggested here are nothing more than an
+educated guess that is valid today. There are no guarantees that an
+algorithm will remain unbreakable or that these values will remain
+constant in time. There could be scientific breakthroughs that cannot
+be predicted or total failure of the current public key systems by
+quantum computers. On the other hand though the cryptosystems used in
+TLS are selected in a conservative way and such catastrophic
+breakthroughs or failures are believed to be unlikely.
+The NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
+table.
+
+When using @acronym{GnuTLS} and a decision on bit sizes for a public
+key algorithm is required, use of the following functions is  
+recommended:
+
address@hidden
+
address@hidden
+
+Those functions will convert a human understandable security parameter
+of @code{gnutls_sec_param_t} type, to a number of bits suitable for a public 
+key algorithm.
+
+The following functions will set the minimum acceptable group size for 
Diffie-Hellman
+and SRP authentication. 
address@hidden,gnutls_srp_set_prime_bits}
+
+
 @node Advanced topics
 @section Advanced topics
 
@@ -1385,158 +1486,3 @@ imposed by the compatibility layer include:
 
 @end itemize
 
address@hidden Using the cryptographic library
address@hidden Using the cryptographic library
-
address@hidden is not a low-level cryptographic library, i.e., 
-it does not provide access to basic cryptographic primitives. However
-it abstracts the internal cryptographic back-end (see @ref{Cryptographic 
Backend}),
-providing symmetric crypto, hash and HMAC algorithms, as well access
-to the random number generation.
-
address@hidden
-* Symmetric cryptography::
-* Hash and HMAC functions::
-* Random number generation::
address@hidden menu
-
address@hidden Symmetric cryptography
address@hidden Symmetric cryptography
address@hidden symmetric cryptography
-
-The available functions to access symmetric crypto algorithms operations
-are shown below. The supported algorithms are the algorithms required by the 
TLS protocol.
-They are listed in @ref{tab:ciphers}.
-
address@hidden,gnutls_cipher_encrypt2,gnutls_cipher_decrypt2,gnutls_cipher_set_iv,gnutls_cipher_deinit}
-
-In order to support authenticated encryption with associated data (AEAD) 
algorithms the following
-functions are provided to set the associated data and retrieve the 
authentication tag.
-
address@hidden,gnutls_cipher_tag}
-
address@hidden Hash and HMAC functions
address@hidden Hash and HMAC functions
address@hidden hash functions
address@hidden HMAC functions
-
-The available operations to access hash functions and hash-MAC (HMAC) 
algorithms
-are shown below. HMAC algorithms provided keyed hash functionality. They 
supported HMAC algorithms are listed in @ref{tab:macs}.
-
address@hidden,gnutls_hmac,gnutls_hmac_output,gnutls_hmac_deinit,gnutls_hmac_get_len,gnutls_hmac_fast}
-
-The available functions to access hash functions are shown below. The 
supported hash functions
-are the same as the HMAC algorithms.
-
address@hidden,gnutls_hash,gnutls_hash_output,gnutls_hash_deinit,gnutls_hash_get_len,gnutls_hash_fast}
-
address@hidden Random number generation
address@hidden Random number generation
address@hidden random numbers
-
-Access to the random number generator is provided using the 
@funcref{gnutls_rnd}
-function. It allows obtaining random data of various levels.
-
address@hidden,The random number levels.}
address@hidden
-
address@hidden Selecting cryptographic key sizes
address@hidden Selecting cryptographic key sizes
address@hidden key sizes
-
-Because many algorithms are involved in TLS, it is not easy to set
-a consistent security level.  For this reason in @ref{tab:key-sizes} we
-present some correspondence between key sizes of symmetric algorithms
-and public key algorithms based on @xcite{ECRYPT}. 
-Those can be used to generate certificates with
-appropriate key sizes as well as select parameters for Diffie-Hellman and SRP
-authentication.
-
address@hidden Table,tab:key-sizes
address@hidden @columnfractions .10 .12 .10 .20 .32
-
address@hidden Security bits @tab RSA, DH and SRP parameter size @tab ECC key 
size @tab Security parameter @tab Description
-
address@hidden <72
address@hidden <1008
address@hidden <160
address@hidden @code{INSECURE}
address@hidden Considered to be insecure
-
address@hidden 72
address@hidden 1008
address@hidden 160
address@hidden @code{WEAK}
address@hidden Short term protection against small organizations
-
address@hidden 80
address@hidden 1248
address@hidden 160
address@hidden @code{LOW}
address@hidden Very short term protection against agencies
-
address@hidden 96
address@hidden 1776
address@hidden 192
address@hidden @code{LEGACY}
address@hidden Legacy standard level
-
address@hidden 112
address@hidden 2432
address@hidden 224
address@hidden @code{NORMAL}
address@hidden Medium-term protection
-
address@hidden 128
address@hidden 3248
address@hidden 256
address@hidden @code{HIGH}
address@hidden Long term protection
-
address@hidden 256
address@hidden 15424
address@hidden 512
address@hidden @code{ULTRA}
address@hidden Foreseeable future
-
address@hidden multitable
address@hidden sizes and security parameters.}
address@hidden float
-
-The first column  provides a security parameter in a number of bits. This
-gives an indication of the number of combinations to be tried by an adversary
-to brute force a key. For example to test all possible keys in a 112 bit 
security parameter
address@hidden combinations have to be tried. For today's technology this is 
infeasible.
-The next two columns correlate the security
-parameter with actual bit sizes of parameters for DH, RSA, SRP and ECC 
algorithms.
-A mapping to @code{gnutls_sec_param_t} value is given for each security 
parameter, on
-the next column, and finally a brief description of the level.
-
address@hidden @showenumdesc{gnutls_sec_param_t,The @address@hidden 
enumeration.}
-
-Note, however, that the values suggested here are nothing more than an
-educated guess that is valid today. There are no guarantees that an
-algorithm will remain unbreakable or that these values will remain
-constant in time. There could be scientific breakthroughs that cannot
-be predicted or total failure of the current public key systems by
-quantum computers. On the other hand though the cryptosystems used in
-TLS are selected in a conservative way and such catastrophic
-breakthroughs or failures are believed to be unlikely.
-The NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
-table.
-
-When using @acronym{GnuTLS} and a decision on bit sizes for a public
-key algorithm is required, use of the following functions is  
-recommended:
-
address@hidden
-
address@hidden
-
-Those functions will convert a human understandable security parameter
-of @code{gnutls_sec_param_t} type, to a number of bits suitable for a public 
-key algorithm.
-
-The following functions will set the minimum acceptable group size for 
Diffie-Hellman
-and SRP authentication. 
address@hidden,gnutls_srp_set_prime_bits}
diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index b1673b8..415ded8 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -154,6 +154,7 @@ Documentation License''.
 * Hardware security modules and abstract key types::
 * How to use GnuTLS in applications::
 * GnuTLS application examples::
+* Using GnuTLS as a cryptographic library::
 * Other included programs::
 * Internal architecture of GnuTLS::
 * Upgrading from previous versions::
@@ -186,6 +187,8 @@ Documentation License''.
 
 @include cha-gtls-examples.texi
 
address@hidden cha-crypto.texi
+
 @include cha-programs.texi
 
 @include cha-internals.texi
diff --git a/lib/x509/privkey.c b/lib/x509/privkey.c
index 2b91e70..1a81971 100644
--- a/lib/x509/privkey.c
+++ b/lib/x509/privkey.c
@@ -561,7 +561,7 @@ failover:
 /**
  * gnutls_x509_privkey_import2:
  * @key: The structure to store the parsed key
- * @data: The DER or PEM encoded certificate.
+ * @data: The DER or PEM encoded key.
  * @format: One of DER or PEM
  * @password: A password (optional)
  * @flags: an ORed sequence of gnutls_pkcs_encrypt_flags_t


hooks/post-receive
-- 
GNU gnutls