diff options
author | Nikos Mavrogiannopoulos <nmav@gnutls.org> | 2012-10-09 20:53:35 +0200 |
---|---|---|
committer | Nikos Mavrogiannopoulos <nmav@gnutls.org> | 2012-10-09 20:53:51 +0200 |
commit | f74101bf4114d625cdac874cbcac4a1ddc9688c8 (patch) | |
tree | 6cf53f2cf9beb797c2dd997c41b5e36da04f049c | |
parent | 1c601bb18f6674f84239f8a4e35f170e022b85d8 (diff) | |
download | gnutls-f74101bf4114d625cdac874cbcac4a1ddc9688c8.tar.gz |
Documentation updates
-rw-r--r-- | doc/cha-cert-auth.texi | 2 | ||||
-rw-r--r-- | doc/cha-cert-auth2.texi | 16 | ||||
-rw-r--r-- | doc/cha-gtls-app.texi | 66 | ||||
-rw-r--r-- | doc/cha-intro-tls.texi | 18 | ||||
-rw-r--r-- | doc/cha-library.texi | 1 | ||||
-rw-r--r-- | doc/invoke-certtool.texi | 28 | ||||
-rwxr-xr-x | doc/scripts/mytexi2latex | 2 | ||||
-rw-r--r-- | src/certtool-args.c | 79 | ||||
-rw-r--r-- | src/certtool-args.def | 6 | ||||
-rw-r--r-- | src/certtool-args.h | 2 |
10 files changed, 130 insertions, 90 deletions
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi index bea6225622..e6c7c963e3 100644 --- a/doc/cha-cert-auth.texi +++ b/doc/cha-cert-auth.texi @@ -299,7 +299,7 @@ Although the verification of a certificate path indicates that the certificate is signed by trusted authority, does not reveal anything about the peer's identity. It is required to verify if the certificate's owner is the one you expect. For more information -consult @ref{gnutls_x509_crt_check_hostname}, section @ref{ex:verify} for an example, and @xcite{RFC2818}. +consult @funcref{gnutls_x509_crt_check_hostname}, section @ref{ex:verify} for an example, and @xcite{RFC2818}. @node OpenPGP certificates diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi index 6ce6d7a3b5..a89b2ed08d 100644 --- a/doc/cha-cert-auth2.texi +++ b/doc/cha-cert-auth2.texi @@ -116,7 +116,8 @@ functions that return other fields of the CRL structure are also provided. The following functions can be used to generate a CRL. -@showfuncE{gnutls_x509_crl_set_version,gnutls_x509_crl_set_crt_serial,gnutls_x509_crl_set_crt,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update} +@showfuncB{gnutls_x509_crl_set_version,gnutls_x509_crl_set_crt_serial} +@showfuncC{gnutls_x509_crl_set_crt,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update} The @funcref{gnutls_x509_crl_sign2} and @funcref{gnutls_x509_crl_privkey_sign} functions sign the revocation list with a private key. The latter function @@ -255,16 +256,18 @@ The issuing time of the revocation information. @item nextUpdate @tab The issuing time of the revocation information that will update that one. +@item @tab Revoked certificates + @item certificate status @tab The status of the certificate. @item certificate serial @tab The certificate's serial number. -@item Revocation time @tab +@item revocationTime @tab The time the certificate was revoked. -@item Revocation reason @tab +@item revocationReason @tab The reason the certificate was revoked. @end multitable @@ -345,11 +348,12 @@ helper function @funcref{gnutls_pkcs12_simple_parse} is provided. For more advanced uses, manual parsing of the structure is required using the functions below. -@showfuncdesc{gnutls_pkcs12_simple_parse} +@showfuncD{gnutls_pkcs12_get_bag,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt,gnutls_pkcs12_bag_get_count} -@showfuncC{gnutls_pkcs12_get_bag,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt} +@showfuncdesc{gnutls_pkcs12_simple_parse} +@showfuncC{gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name} -@showfuncD{gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name} +@page The functions below are used to generate a PKCS #12 structure. An example of their usage is also shown. diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi index 7b24915380..8bd5d92a07 100644 --- a/doc/cha-gtls-app.texi +++ b/doc/cha-gtls-app.texi @@ -961,9 +961,10 @@ for the acceptable security levels.} than their elliptic curves counterpart requires parameters to be generated and associated with a credentials structure by the server (see @ref{Parameter generation}). -The available special keywords are shown in @ref{tab:prio-special}. +The available special keywords are shown in @ref{tab:prio-special1} +and @ref{tab:prio-special2}. -@float Table,tab:prio-special +@float Table,tab:prio-special1 @multitable @columnfractions .45 .45 @headitem Keyword @tab Description @@ -979,6 +980,25 @@ will prevent the sending of any TLS extensions in client side. Note that TLS 1.2 requires extensions to be used, as well as safe renegotiation thus this option must be used with care. +@item %SERVER_PRECEDENCE @tab +The ciphersuite will be selected according to server priorities +and not the client's. + +@item %SSL3_RECORD_VERSION @tab +will use SSL3.0 record version in client hello. +This is the default. + +@item %LATEST_RECORD_VERSION @tab +will use the latest TLS version record version in client hello. + +@end multitable +@caption{Special priority string keywords.} +@end float + +@float Table,tab:prio-special2 +@multitable @columnfractions .45 .45 +@headitem Keyword @tab Description + @item %STATELESS_COMPRESSION @tab will disable keeping state across records when compressing. This may help to mitigate attacks when compression is used but an attacker @@ -986,14 +1006,9 @@ is in control of input data. This has to be used only when the data that are possibly controlled by an attacker are placed in separate records. -@item %SERVER_PRECEDENCE @tab -The ciphersuite will be selected according to server priorities -and not the client's. - @item %DISABLE_SAFE_RENEGOTIATION @tab -will disable safe renegotiation +will completely disable safe renegotiation completely. Do not use unless you know what you are doing. -Testing purposes only. @item %UNSAFE_RENEGOTIATION @tab will allow handshakes and re-handshakes @@ -1015,13 +1030,6 @@ will enforce safe renegotiation. Clients and servers will refuse to talk to an insecure peer. Currently this causes interoperability problems, but is required for full protection. -@item %SSL3_RECORD_VERSION @tab -will use SSL3.0 record version in client hello. -This is the default. - -@item %LATEST_RECORD_VERSION @tab -will use the latest TLS version record version in client hello. - @item %VERIFY_ALLOW_SIGN_RSA_MD5 @tab will allow RSA-MD5 signatures in certificate chains. @@ -1029,13 +1037,14 @@ will allow RSA-MD5 signatures in certificate chains. will allow V1 CAs in chains. @end multitable -@caption{Special priority string keywords.} +@caption{More priority string keywords.} @end float Finally the ciphersuites enabled by any priority string can be listed using the @code{gnutls-cli} application (see @ref{gnutls-cli Invocation}), or by using the priority functions as in @ref{Listing the ciphersuites in a priority string}. +@page Example priority strings are: @example The default priority without the HMAC-MD5: @@ -1047,9 +1056,12 @@ Specifying RSA with AES-128-CBC: Specifying the defaults except ARCFOUR-128: "NORMAL:-ARCFOUR-128" -Enabling the 128-bit secure ciphers, while disabling SSL 3.0 and -enabling compression: +Enabling the 128-bit secure ciphers, while disabling SSL 3.0 and enabling compression: "SECURE128:-VERS-SSL3.0:+COMP-DEFLATE" + +Enabling the 128-bit and 192-bit secure ciphers, while disabling all TLS versions +except TLS 1.2: + "SECURE128:+SECURE192:-VERS-TLS-ALL:+VERS-TLS1.2" @end example @node Advanced and other topics @@ -1086,12 +1098,6 @@ even when requested to. The expiration is to prevent temporal session keys from becoming long-term keys. Also note that as a client you must enable, using the priority functions, at least the algorithms used in the last session. -It is highly recommended for clients to enable the session ticket extension using -@funcref{gnutls_session_ticket_enable_client} in order to allow resumption with -servers that do not store any state. - -@showfuncA{gnutls_session_ticket_enable_client} - @showfuncdesc{gnutls_session_is_resumed} @subsubheading Server side @@ -1367,6 +1373,18 @@ authentication. @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 diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi index aa5eaa2dd1..bf9f174c71 100644 --- a/doc/cha-intro-tls.texi +++ b/doc/cha-intro-tls.texi @@ -443,19 +443,20 @@ To resume a TLS session the server normally store session parameters. This complicates deployment, and could be avoiding by delegating the storage to the client. Because session parameters are sensitive they are encrypted and authenticated with a key only known to the server and then sent to the -client. The Session Tickets in RFC 5077 @xcite{TLSTKT}, describe this -idea, which is implemented in GnuTLS. +client. The Session Tickets extension is described in RFC 5077 @xcite{TLSTKT}. + +Since version 3.1.3 GnuTLS clients transparently support session tickets. @node HeartBeat @subsection HeartBeat @cindex TLS extensions @cindex heartbeat -The TLS extension which allows to ping and receive replies from the peer, -described in @xcite{RFC6520}. This extension is disabled by default and +This TLS extension allows to ping and receive confirmation from the peer, +is described in @xcite{RFC6520}. The extension is disabled by default and @funcref{gnutls_heartbeat_enable} can be used to enable it. A policy may be negotiated to only allow sending heartbeat messages or sending and receiving. -The session policy can be checked with @funcref{gnutls_heartbeat_allowed}. +The current session policy can be checked with @funcref{gnutls_heartbeat_allowed}. The requests coming from the peer result to @code{GNUTLS_@-E_@-HERTBEAT_@-PING_@-RECEIVED} being returned from the receive function. Ping requests to peer can be send via @funcref{gnutls_heartbeat_ping}. @@ -571,7 +572,7 @@ can be used both by clients and servers. The Online Certificate Status Protocol (OCSP) is a protocol that allows the client to verify the server certificate for revocation without messing with certificate revocation lists. Its drawback is that it requires the client -to connect to the server's CA OCSP server and ask for the status of the +to connect to the server's CA OCSP server and request the status of the certificate. This extension however, enables a TLS server to include its CA OCSP server response in the handshake. That is an HTTPS server may periodically run @code{ocsptool} (see @ref{ocsptool Invocation}) to obtain @@ -579,12 +580,13 @@ its certificate revocation status and serve it to the clients. This reduces the number of connections a client needs to perform to access a secure server. -Server functions: @showfuncB{gnutls_certificate_set_ocsp_status_request_function,gnutls_certificate_set_ocsp_status_request_file} -Client functions: @showfuncA{gnutls_ocsp_status_request_enable_client} +Since version 3.1.3 GnuTLS clients transparently support the certificate status +request. + @include sec-tls-app.texi @node On SSL 2 and older protocols diff --git a/doc/cha-library.texi b/doc/cha-library.texi index 0278eaa536..338658af7f 100644 --- a/doc/cha-library.texi +++ b/doc/cha-library.texi @@ -95,6 +95,7 @@ options are given. --disable-extra-pki --disable-openpgp-authentication --disable-openssl-compatibility +--disable-libdane --without-p11-kit --without-tpm @end verbatim diff --git a/doc/invoke-certtool.texi b/doc/invoke-certtool.texi index 4891908faa..21f3bcb83f 100644 --- a/doc/invoke-certtool.texi +++ b/doc/invoke-certtool.texi @@ -7,7 +7,7 @@ # # DO NOT EDIT THIS FILE (invoke-certtool.texi) # -# It has been AutoGen-ed October 8, 2012 at 04:55:06 PM by AutoGen 5.16 +# It has been AutoGen-ed October 9, 2012 at 08:27:51 PM by AutoGen 5.16 # From the definitions ../src/certtool-args.def # and the template file agtexi-cmd.tpl @end ignore @@ -42,6 +42,8 @@ USAGE: certtool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... -d, --debug=num Enable debugging. - It must be in the range: 0 to 9999 + -V, --verbose More verbose output + - may appear multiple times --infile=file Input file - file must pre-exist --outfile=str Output file @@ -114,8 +116,8 @@ USAGE: certtool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... --dane-port=num Specify the port number for the DANE data. --dane-ca Whether the provided certificate or public key is a Certificate authority. - --dane-local Whether the provided certificate or public key is an unsigned local -entity. + --dane-full-x509 Use the hash of the X.509 certificate, rather than the public key. + --dane-local The provided certificate or public key is a local entity. -v, --version[=arg] Output version information and exit -h, --help Display extended usage information and exit -!, --more-help Extended usage information passed thru pager @@ -323,12 +325,18 @@ This command specifies the protocol for the service set in the DANE data. This is the ``whether the provided certificate or public key is a certificate authority.'' option. Marks the DANE RR as a CA certificate if specified. +@anchor{certtool dane-full-x509} +@subheading dane-full-x509 option +@cindex certtool-dane-full-x509 + +This is the ``use the hash of the x.509 certificate, rather than the public key.'' option. +This option forces the generated record to contain the hash of the full X.509 certificate. By default only the hash of the public key is used. @anchor{certtool dane-local} @subheading dane-local option @cindex certtool-dane-local -This is the ``whether the provided certificate or public key is an unsigned local entity.'' option. -DANE distinguishes certificates and public keys offered via the DNSSEC to trusted and local entities. Use this flag if this is a local entity. +This is the ``the provided certificate or public key is a local entity.'' option. +DANE distinguishes certificates and public keys offered via the DNSSEC to trusted and local entities. Use this flag if this is a local (and possibly unsigned) entity. @anchor{certtool exit status} @subheading certtool exit status @@ -462,8 +470,10 @@ To verify a Certificate Revocation List (CRL) do: $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem @end example -@subheading DANE RR generation -To create a DANE resource record for a CA signed certificate use the following commands. +@subheading DANE TLSA RR generation + + +To create a DANE TLSA resource record for a CA signed certificate use the following commands. @example $ certtool --dane-rr --dane-host www.example.com --load-certificate cert.pem @@ -475,6 +485,10 @@ $ certtool --dane-rr --dane-host www.example.com --load-certificate cert.pem \ --dane-local @end example +The latter is useful to add in your DNS entry even if your certificate is signed +by a CA. That way even users who do not trust your CA will be able to verify your +certificate using DANE. + In order to create a record for the signer of your certificate use: @example $ certtool --dane-rr --dane-host www.example.com --load-certificate cert.pem \ diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex index a4b35b2af8..fe9176c52e 100755 --- a/doc/scripts/mytexi2latex +++ b/doc/scripts/mytexi2latex @@ -341,6 +341,8 @@ multitable: } if ($verbatim == 0) { + $line =~ s/\</\$<\$/g; + $line =~ s/\>/\$>\$/g; $line =~ s/\_/\\_/g; $line =~ s/\~/\\~/g; $line =~ s/\%(?!c)/\\%/g; diff --git a/src/certtool-args.c b/src/certtool-args.c index 3dd21ad9a3..d416fe6616 100644 --- a/src/certtool-args.c +++ b/src/certtool-args.c @@ -2,7 +2,7 @@ * * DO NOT EDIT THIS FILE (certtool-args.c) * - * It has been AutoGen-ed October 9, 2012 at 07:10:23 PM by AutoGen 5.16 + * It has been AutoGen-ed October 9, 2012 at 08:27:12 PM by AutoGen 5.16 * From the definitions certtool-args.def * and the template file options * @@ -67,7 +67,7 @@ extern FILE * option_usage_fp; /* * certtool option static const strings */ -static char const certtool_opt_strs[5254] = +static char const certtool_opt_strs[5231] = /* 0 */ "certtool @VERSION@\n" "Copyright (C) 2000-2012 Free Software Foundation, all rights reserved.\n" "This is free software. It is licensed for use, modification and\n" @@ -264,30 +264,29 @@ static char const certtool_opt_strs[5254] = "authority.\0" /* 4493 */ "DANE_CA\0" /* 4501 */ "dane-ca\0" -/* 4509 */ "Use the hash of the full X.509 certificate, rather than the public key.\0" -/* 4581 */ "DANE_FULL_X509\0" -/* 4596 */ "dane-full-x509\0" -/* 4611 */ "Whether the provided certificate or public key is an unsigned local\n" - "entity.\0" -/* 4687 */ "DANE_LOCAL\0" -/* 4698 */ "dane-local\0" -/* 4709 */ "Display extended usage information and exit\0" -/* 4753 */ "help\0" -/* 4758 */ "Extended usage information passed thru pager\0" -/* 4803 */ "more-help\0" -/* 4813 */ "Output version information and exit\0" -/* 4849 */ "version\0" -/* 4857 */ "CERTTOOL\0" -/* 4866 */ "certtool - GnuTLS PKCS #11 tool - Ver. @VERSION@\n" +/* 4509 */ "Use the hash of the X.509 certificate, rather than the public key.\0" +/* 4576 */ "DANE_FULL_X509\0" +/* 4591 */ "dane-full-x509\0" +/* 4606 */ "The provided certificate or public key is a local entity.\0" +/* 4664 */ "DANE_LOCAL\0" +/* 4675 */ "dane-local\0" +/* 4686 */ "Display extended usage information and exit\0" +/* 4730 */ "help\0" +/* 4735 */ "Extended usage information passed thru pager\0" +/* 4780 */ "more-help\0" +/* 4790 */ "Output version information and exit\0" +/* 4826 */ "version\0" +/* 4834 */ "CERTTOOL\0" +/* 4843 */ "certtool - GnuTLS PKCS #11 tool - Ver. @VERSION@\n" "USAGE: %s [ -<flag> [<val>] | --<name>[{=| }<val>] ]...\n\0" -/* 4973 */ "bug-gnutls@gnu.org\0" -/* 4992 */ "\n\n\0" -/* 4995 */ "\n" +/* 4950 */ "bug-gnutls@gnu.org\0" +/* 4969 */ "\n\n\0" +/* 4972 */ "\n" "Tool to parse and generate X.509 certificates, requests and private keys.\n" "It can be used interactively or non interactively by specifying the\n" "template command line option.\n\0" -/* 5169 */ "certtool @VERSION@\0" -/* 5188 */ "certtool [options] [url]\n" +/* 5146 */ "certtool @VERSION@\0" +/* 5165 */ "certtool [options] [url]\n" "certtool --help for usage instructions.\n"; /* @@ -808,26 +807,26 @@ static int const aDane_RrMustList[] = { * dane-full-x509 option description: */ #define DANE_FULL_X509_DESC (certtool_opt_strs+4509) -#define DANE_FULL_X509_NAME (certtool_opt_strs+4581) -#define DANE_FULL_X509_name (certtool_opt_strs+4596) +#define DANE_FULL_X509_NAME (certtool_opt_strs+4576) +#define DANE_FULL_X509_name (certtool_opt_strs+4591) #define DANE_FULL_X509_FLAGS (OPTST_DISABLED) /* * dane-local option description: */ -#define DANE_LOCAL_DESC (certtool_opt_strs+4611) -#define DANE_LOCAL_NAME (certtool_opt_strs+4687) -#define DANE_LOCAL_name (certtool_opt_strs+4698) +#define DANE_LOCAL_DESC (certtool_opt_strs+4606) +#define DANE_LOCAL_NAME (certtool_opt_strs+4664) +#define DANE_LOCAL_name (certtool_opt_strs+4675) #define DANE_LOCAL_FLAGS (OPTST_DISABLED) /* * Help/More_Help/Version option descriptions: */ -#define HELP_DESC (certtool_opt_strs+4709) -#define HELP_name (certtool_opt_strs+4753) +#define HELP_DESC (certtool_opt_strs+4686) +#define HELP_name (certtool_opt_strs+4730) #ifdef HAVE_WORKING_FORK -#define MORE_HELP_DESC (certtool_opt_strs+4758) -#define MORE_HELP_name (certtool_opt_strs+4803) +#define MORE_HELP_DESC (certtool_opt_strs+4735) +#define MORE_HELP_name (certtool_opt_strs+4780) #define MORE_HELP_FLAGS (OPTST_IMM | OPTST_NO_INIT) #else #define MORE_HELP_DESC NULL @@ -840,8 +839,8 @@ static int const aDane_RrMustList[] = { # define VER_FLAGS (OPTST_SET_ARGTYPE(OPARG_TYPE_STRING) | \ OPTST_ARG_OPTIONAL | OPTST_IMM | OPTST_NO_INIT) #endif -#define VER_DESC (certtool_opt_strs+4813) -#define VER_name (certtool_opt_strs+4849) +#define VER_DESC (certtool_opt_strs+4790) +#define VER_name (certtool_opt_strs+4826) /* * Declare option callback procedures */ @@ -1651,14 +1650,14 @@ static tOptDesc optDesc[OPTION_CT] = { * * Define the certtool Option Environment */ -#define zPROGNAME (certtool_opt_strs+4857) -#define zUsageTitle (certtool_opt_strs+4866) +#define zPROGNAME (certtool_opt_strs+4834) +#define zUsageTitle (certtool_opt_strs+4843) #define zRcName NULL #define apzHomeList NULL -#define zBugsAddr (certtool_opt_strs+4973) -#define zExplain (certtool_opt_strs+4992) -#define zDetail (certtool_opt_strs+4995) -#define zFullVersion (certtool_opt_strs+5169) +#define zBugsAddr (certtool_opt_strs+4950) +#define zExplain (certtool_opt_strs+4969) +#define zDetail (certtool_opt_strs+4972) +#define zFullVersion (certtool_opt_strs+5146) /* extracted from optcode.tlib near line 350 */ #if defined(ENABLE_NLS) @@ -1672,7 +1671,7 @@ static tOptDesc optDesc[OPTION_CT] = { #define certtool_full_usage (NULL) -#define certtool_short_usage (certtool_opt_strs+5188) +#define certtool_short_usage (certtool_opt_strs+5165) #endif /* not defined __doxygen__ */ diff --git a/src/certtool-args.def b/src/certtool-args.def index cfc9ffc65b..5fce8721a2 100644 --- a/src/certtool-args.def +++ b/src/certtool-args.def @@ -393,14 +393,14 @@ flag = { flag = { name = dane-full-x509; - descrip = "Use the hash of the full X.509 certificate, rather than the public key."; + descrip = "Use the hash of the X.509 certificate, rather than the public key."; doc = "This option forces the generated record to contain the hash of the full X.509 certificate. By default only the hash of the public key is used."; }; flag = { name = dane-local; - descrip = "Whether the provided certificate or public key is an unsigned local entity."; - doc = "DANE distinguishes certificates and public keys offered via the DNSSEC to trusted and local entities. Use this flag if this is a local entity."; + descrip = "The provided certificate or public key is a local entity."; + doc = "DANE distinguishes certificates and public keys offered via the DNSSEC to trusted and local entities. Use this flag if this is a local (and possibly unsigned) entity."; }; doc-section = { diff --git a/src/certtool-args.h b/src/certtool-args.h index 8360fc24ac..1a4273c1fc 100644 --- a/src/certtool-args.h +++ b/src/certtool-args.h @@ -2,7 +2,7 @@ * * DO NOT EDIT THIS FILE (certtool-args.h) * - * It has been AutoGen-ed October 9, 2012 at 07:10:23 PM by AutoGen 5.16 + * It has been AutoGen-ed October 9, 2012 at 08:27:12 PM by AutoGen 5.16 * From the definitions certtool-args.def * and the template file options * |