[SCM] GNU gnutls branch, master, updated. gnutls_3_1_4-21-g96c38a6
"Nikos Mavrogiannopoulos" <[email protected]> Sat, 17 Nov 2012 15:52:09 +0000
| Newsgroups | gmane.comp.encryption.gpg.gnutls.cvs |
|---|---|
| Message-ID | <[email protected]> |
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 <[email protected]>
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.
+
+@subheading High level functionality
+Generic and higher level private key import functions are available, that
+will auto-detect the encrypted key format.
+
+@showfuncdesc{gnutls_x509_privkey_import2}
+
+@showfuncdesc{gnutls_privkey_import_x509_raw}
@subheading @acronym{PKCS} #8 structures
@cindex PKCS #8
@@ -367,7 +374,7 @@ of their usage is also shown.
@verbatiminclude examples/ex-pkcs12.c
-@subheading Other structures
+@subheading 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.
-@showfuncB{gnutls_x509_privkey_import2,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 @@
+@node Using GnuTLS as a cryptographic library
+@chapter Using GnuTLS as a cryptographic library
+
+@acronym{GnuTLS} 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.
+
+@menu
+* Symmetric cryptography::
+* Hash and HMAC functions::
+* Random number generation::
+@end menu
+
+@node Symmetric cryptography
+@section Symmetric cryptography
+@cindex 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}.
+
+@showfuncE{gnutls_cipher_init,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.
+
+@showfuncB{gnutls_cipher_add_auth,gnutls_cipher_tag}
+
+@node Hash and HMAC functions
+@section Hash and HMAC functions
+@cindex hash functions
+@cindex 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}.
+
+@showfuncF{gnutls_hmac_init,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.
+
+@showfuncF{gnutls_hash_init,gnutls_hash,gnutls_hash_output,gnutls_hash_deinit,gnutls_hash_get_len,gnutls_hash_fast}
+
+@node Random number generation
+@section Random number generation
+@cindex random numbers
+
+Access to the random number generator is provided using the @funcref{gnutls_rnd}
+function. It allows obtaining random data of various levels.
+
+@showenumdesc{gnutls_rnd_level_t,The random number levels.}
+@showfuncdesc{gnutls_rnd}
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
+@node Selecting cryptographic key sizes
+@section Selecting cryptographic key sizes
+@cindex 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.
+
+@float Table,tab:key-sizes
+@multitable @columnfractions .10 .12 .10 .20 .32
+
+@headitem Security bits @tab RSA, DH and SRP parameter size @tab ECC key size @tab Security parameter @tab Description
+
+@item <72
+@tab <1008
+@tab <160
+@tab @code{INSECURE}
+@tab Considered to be insecure
+
+@item 72
+@tab 1008
+@tab 160
+@tab @code{WEAK}
+@tab Short term protection against small organizations
+
+@item 80
+@tab 1248
+@tab 160
+@tab @code{LOW}
+@tab Very short term protection against agencies
+
+@item 96
+@tab 1776
+@tab 192
+@tab @code{LEGACY}
+@tab Legacy standard level
+
+@item 112
+@tab 2432
+@tab 224
+@tab @code{NORMAL}
+@tab Medium-term protection
+
+@item 128
+@tab 3248
+@tab 256
+@tab @code{HIGH}
+@tab Long term protection
+
+@item 256
+@tab 15424
+@tab 512
+@tab @code{ULTRA}
+@tab Foreseeable future
+
+@end multitable
+@caption{Key sizes and security parameters.}
+@end 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
+@math{2^{112}} 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.
+
+@c @showenumdesc{gnutls_sec_param_t,The @code{gnutls_sec_@-param_t} 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:
+
+@showfuncdesc{gnutls_sec_param_to_pk_bits}
+
+@showfuncdesc{gnutls_pk_bits_to_sec_param}
+
+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.
+@showfuncB{gnutls_dh_set_prime_bits,gnutls_srp_set_prime_bits}
+
+
@node Advanced topics
@section Advanced topics
@@ -1385,158 +1486,3 @@ imposed by the compatibility layer include:
@end itemize
-@node Using the cryptographic library
-@section Using the cryptographic library
-
-@acronym{GnuTLS} 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.
-
-@menu
-* Symmetric cryptography::
-* Hash and HMAC functions::
-* Random number generation::
-@end menu
-
-@node Symmetric cryptography
-@subsection Symmetric cryptography
-@cindex 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}.
-
-@showfuncE{gnutls_cipher_init,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.
-
-@showfuncB{gnutls_cipher_add_auth,gnutls_cipher_tag}
-
-@node Hash and HMAC functions
-@subsection Hash and HMAC functions
-@cindex hash functions
-@cindex 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}.
-
-@showfuncF{gnutls_hmac_init,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.
-
-@showfuncF{gnutls_hash_init,gnutls_hash,gnutls_hash_output,gnutls_hash_deinit,gnutls_hash_get_len,gnutls_hash_fast}
-
-@node Random number generation
-@subsection Random number generation
-@cindex random numbers
-
-Access to the random number generator is provided using the @funcref{gnutls_rnd}
-function. It allows obtaining random data of various levels.
-
-@showenumdesc{gnutls_rnd_level_t,The random number levels.}
-@showfuncdesc{gnutls_rnd}
-
-@node Selecting cryptographic key sizes
-@section Selecting cryptographic key sizes
-@cindex 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.
-
-@float Table,tab:key-sizes
-@multitable @columnfractions .10 .12 .10 .20 .32
-
-@headitem Security bits @tab RSA, DH and SRP parameter size @tab ECC key size @tab Security parameter @tab Description
-
-@item <72
-@tab <1008
-@tab <160
-@tab @code{INSECURE}
-@tab Considered to be insecure
-
-@item 72
-@tab 1008
-@tab 160
-@tab @code{WEAK}
-@tab Short term protection against small organizations
-
-@item 80
-@tab 1248
-@tab 160
-@tab @code{LOW}
-@tab Very short term protection against agencies
-
-@item 96
-@tab 1776
-@tab 192
-@tab @code{LEGACY}
-@tab Legacy standard level
-
-@item 112
-@tab 2432
-@tab 224
-@tab @code{NORMAL}
-@tab Medium-term protection
-
-@item 128
-@tab 3248
-@tab 256
-@tab @code{HIGH}
-@tab Long term protection
-
-@item 256
-@tab 15424
-@tab 512
-@tab @code{ULTRA}
-@tab Foreseeable future
-
-@end multitable
-@caption{Key sizes and security parameters.}
-@end 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
-@math{2^{112}} 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.
-
-@c @showenumdesc{gnutls_sec_param_t,The @code{gnutls_sec_@-param_t} 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:
-
-@showfuncdesc{gnutls_sec_param_to_pk_bits}
-
-@showfuncdesc{gnutls_pk_bits_to_sec_param}
-
-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.
-@showfuncB{gnutls_dh_set_prime_bits,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
+@include 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