From dff23649552500f42e4c9cfb3ce491f26dce33e6 Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Tue, 21 Jun 2011 01:42:39 +0200 Subject: documentation updates. --- doc/cha-auth.texi | 74 +++++++++++------------ doc/cha-cert-auth.texi | 120 ++++++++++++++++++++++--------------- doc/cha-gtls-app.texi | 5 +- doc/cha-intro-tls.texi | 152 +++++++++++++++++++++++++++-------------------- doc/cha-library.texi | 10 ++-- doc/cha-programs.texi | 8 +-- doc/scripts/mytexi2latex | 25 +++++--- 7 files changed, 224 insertions(+), 170 deletions(-) diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi index edfb36d161..9f85e2ff10 100644 --- a/doc/cha-auth.texi +++ b/doc/cha-auth.texi @@ -114,28 +114,29 @@ certificate authentication. Note that the DHE key exchange methods are generally slower@footnote{It really depends on the group used. Primes with -lesser bits are always faster, but also easier to break. Values less -than 1024 should not be used today} than plain RSA and require Diffie +lesser bits are always faster, but also easier to break. See @ref{Selecting cryptographic key sizes} +for the acceptable security levels.} than plain RSA and require Diffie Hellman parameters to be generated and associated with a credentials structure, by the server. For more information check the @ref{Parameter generation} -section. +section. The key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509} +certificates are shown in @ref{tab:key-exchange}. -Key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509} -certificates: +@float Table,tab:key-exchange +@multitable @columnfractions .3 .7 -@table @code +@headitem Key exchange @tab Description -@item RSA: +@item RSA @tab The RSA algorithm is used to encrypt a key and send it to the peer. The certificate must allow the key to be used for encryption. -@item RSA_EXPORT: +@item RSA_EXPORT @tab The RSA algorithm is used to encrypt a key and send it to the peer. In the EXPORT algorithm, the server signs temporary RSA parameters of 512 bits --- which are considered weak --- and sends them to the client. -@item DHE_RSA: +@item DHE_RSA @tab The RSA algorithm is used to sign ephemeral Diffie-Hellman parameters which are sent to the peer. The key in the certificate must allow the key to be used for signing. Note that key exchange algorithms which @@ -143,26 +144,28 @@ use ephemeral Diffie-Hellman parameters, offer perfect forward secrecy. That means that even if the private key used for signing is compromised, it cannot be used to reveal past session data. -@item ECDHE_RSA: +@item ECDHE_RSA @tab The RSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman parameters which are sent to the peer. The key in the certificate must allow the key to be used for signing. It also offers perfect forward secrecy. That means that even if the private key used for signing is compromised, it cannot be used to reveal past session data. -@item DHE_DSS: +@item DHE_DSS @tab The DSA algorithm is used to sign ephemeral Diffie-Hellman parameters which are sent to the peer. The certificate must contain DSA parameters to use this key exchange algorithm. DSA is the algorithm of the Digital Signature Standard (DSS). -@item ECDHE_ECDSA: +@item ECDHE_ECDSA @tab The Elliptic curve DSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman parameters which are sent to the peer. The certificate must contain ECDSA parameters to use this key exchange algorithm. -@end table +@end multitable +@caption{Supported key exchange algorithms.} +@end float @node Anonymous authentication @section Anonymous Authentication @@ -241,28 +244,20 @@ authenticated using a certificate with RSA parameters. @end table If clients supporting @acronym{SRP} know the username and password -before the connection, should initialize the client credentials and -call the function @funcref{gnutls_srp_set_client_credentials}. -Alternatively they could specify a callback function by using the -function @funcref{gnutls_srp_set_client_credentials_function}. This has -the advantage that allows probing the server for @acronym{SRP} -support. In that case the callback function will be called twice per -handshake. The first time is before the ciphersuite is negotiated, -and if the callback returns a negative error code, the callback will -be called again if @acronym{SRP} has been negotiated. This uses a -special @acronym{TLS}-@acronym{SRP} handshake idiom in order to avoid, -in interactive applications, to ask the user for @acronym{SRP} -password and username if the server does not negotiate an -@acronym{SRP} ciphersuite. +before the connection, should initialize client credentials and +call @funcref{gnutls_srp_set_client_credentials}. +Alternatively @funcref{gnutls_srp_set_client_credentials_function} +may be used to specify a callback function. +The callback will be called once during the @acronym{TLS} handshake. In server side the default behaviour of @acronym{GnuTLS} is to read the usernames and @acronym{SRP} verifiers from password files. These password files are the ones used by the @emph{Stanford srp libraries} -and can be specified using the -@funcref{gnutls_srp_set_server_credentials_file}. If a different -password file format is to be used, then the function -@funcref{gnutls_srp_set_server_credentials_function}, should be called, -in order to set an appropriate callback. +and @funcref{gnutls_srp_set_server_credentials_file} can be used to +specify them. If a different +password file format is to be used, then +@funcref{gnutls_srp_set_server_credentials_function} should be called, +to set an appropriate callback. Some helper functions such as @@ -306,10 +301,10 @@ exchange. This method offers perfect forward secrecy. @end table Clients supporting @acronym{PSK} should supply the username and key -before the connection to the client credentials by calling the -function @funcref{gnutls_psk_set_client_credentials}. Alternatively they -could specify a callback function by using the function -@funcref{gnutls_psk_set_client_credentials_function}. This has the +before the TLS session is established by calling +@funcref{gnutls_psk_set_client_credentials}. Alternatively +@funcref{gnutls_psk_set_client_credentials_function} can be used to +specify a callback function. This has the advantage that the callback will be called only if @acronym{PSK} has been negotiated. @@ -318,12 +313,13 @@ the usernames and @acronym{PSK} keys from a password file. The password file should contain usernames and keys in hexadecimal format. The name of the password file can be stored to the credentials structure by calling @funcref{gnutls_psk_set_server_credentials_file}. If -a different password file format is to be used, then the function -@funcref{gnutls_psk_set_server_credentials_function}, should be used -instead. +a different password file format is to be used, then +a callback should be set instead by @funcref{gnutls_psk_set_server_credentials_function}. The server can help the client chose a suitable username and password, -by sending a hint. In the server, specify the hint by calling +by sending a hint. Note that there is no common profile for the PSK hint and applications +are discouraged to use it. +A server, may specify the hint by calling @funcref{gnutls_psk_set_server_credentials_hint}. The client can retrieve the hint, for example in the callback function, using @funcref{gnutls_psk_client_get_hint}. diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi index c4675ae4ed..26ca9fd2ae 100644 --- a/doc/cha-cert-auth.texi +++ b/doc/cha-cert-auth.texi @@ -42,29 +42,34 @@ Detailed examples involving X.509 certificates are listed below. An @acronym{X.509} certificate usually contains information about the certificate holder, the signer, a unique serial number, expiration -dates and some other fields @xcite{PKIX} as shown in the table below. +dates and some other fields @xcite{PKIX} as shown in @ref{tab:x509}. -@table @code +@float Table,tab:x509 +@multitable @columnfractions .3 .7 + +@headitem Field @tab Description -@item version: +@item version @tab The field that indicates the version of the certificate. -@item serialNumber: +@item serialNumber @tab This field holds a unique serial number per certificate. -@item issuer: +@item issuer @tab Holds the issuer's distinguished name. -@item validity: +@item validity @tab The activation and expiration dates. -@item subject: +@item subject @tab The subject's distinguished name of the certificate. -@item extensions: +@item extensions @tab The extensions are fields only present in version 3 certificates. -@end table +@end multitable +@caption{X.509 certificate fields.} +@end float The certificate's @emph{subject or issuer name} is not just a single string. It is a Distinguished name and in the @acronym{ASN.1} @@ -85,40 +90,45 @@ Certificate @emph{extensions} are there to include information about the certificate's subject that did not fit in the typical certificate fields. Those may be e-mail addresses, flags that indicate whether the belongs to a CA etc. All the supported @acronym{X.509} version 3 -extensions are shown in the table below. +extensions are shown in @ref{tab:x509-ext}. -@table @code +@float Table,tab:x509-ext +@multitable @columnfractions .3 .2 .5 -@item subject key id (2.5.29.14): +@headitem Extension @tab OID @tab Description + +@item Subject key id @tab 2.5.29.14 @tab An identifier of the key of the subject. -@item authority key id (2.5.29.35): +@item Authority key id @tab 2.5.29.35 @tab An identifier of the authority's key used to sign the certificate. -@item subject alternative name (2.5.29.17): +@item Subject alternative name @tab 2.5.29.17 @tab Alternative names to subject's distinguished name. -@item key usage (2.5.29.15): +@item Key usage @tab 2.5.29.15 @tab Constraints the key's usage of the certificate. -@item extended key usage (2.5.29.37): +@item Extended key usage @tab 2.5.29.37 @tab Constraints the purpose of the certificate. -@item basic constraints (2.5.29.19): +@item Basic constraints @tab 2.5.29.19 @tab Indicates whether this is a CA certificate or not, and specify the maximum path lengths of certificate chains. -@item CRL distribution points (2.5.29.31): +@item CRL distribution points @tab 2.5.29.31 @tab This extension is set by the CA, in order to inform about the issued CRLs. -@item Proxy Certification Information (1.3.6.1.5.5.7.1.14): +@item Proxy Certification Information @tab 1.3.6.1.5.5.7.1.14 @tab Proxy Certificates includes this extension that contains the OID of the proxy policy language used, and can specify limits on the maximum lengths of proxy chains. Proxy Certificates are specified in @xcite{RFC3820}. -@end table +@end multitable +@caption{X.509 certificate extensions.} +@end float In @acronym{GnuTLS} the @acronym{X.509} certificate structures are handled using the @code{gnutls_x509_crt_t} type and the corresponding @@ -185,31 +195,37 @@ authority list has been set via the thus it is not required to setup a trusted list as above. Convenience functions such as @funcref{gnutls_certificate_verify_peers2} are equivalent and will verify the peer's certificate chain -in a TLS session. +in a TLS session. The certificate verification functions output +codes as in @ref{tab:cert-verify}. -@table @code +@float Table,tab:cert-verify +@multitable @columnfractions .55 .45 + +@headitem Flag @tab Description -@item GNUTLS_CERT_INVALID: +@item GNUTLS_CERT_INVALID @tab The certificate is not signed by one of the known authorities, or the signature is invalid. -@item GNUTLS_CERT_REVOKED: +@item GNUTLS_CERT_REVOKED @tab The certificate has been revoked by its CA. -@item GNUTLS_CERT_SIGNER_NOT_FOUND: +@item GNUTLS_CERT_SIGNER_NOT_FOUND @tab The certificate's issuer is not known. This is the case when the issuer is not in the trusted certificates list. -@item GNUTLS_CERT_SIGNER_NOT_CA: +@item GNUTLS_CERT_SIGNER_NOT_CA @tab The certificate's signer was not a CA. This may happen if this was a version 1 certificate, which is common with some CAs, or a version 3 certificate without the basic constrains extension. -@item GNUTLS_CERT_INSECURE_ALGORITHM: +@item GNUTLS_CERT_INSECURE_ALGORITHM @tab The certificate was signed using an insecure algorithm such as MD2 or MD5. These algorithms have been broken and should not be trusted. -@end table +@end multitable +@caption{Certificate verification output flags.} +@end float There is also to possibility to pass some input to the verification functions in the form of flags. For @funcref{gnutls_x509_trust_list_verify_crt} the @@ -217,48 +233,53 @@ flags are passed straightforward, but @funcref{gnutls_certificate_verify_peers2} depends on the flags set by calling @funcref{gnutls_certificate_set_verify_flags}. All the available flags are part of the enumeration -@code{gnutls_certificate_verify_flags} and are explained in the table -below. +@code{gnutls_certificate_verify_flags} and are explained in @ref{tab:cert-flags}. -@table @code -@item GNUTLS_VERIFY_DISABLE_CA_SIGN: +@float Table,tab:cert-flags +@multitable @columnfractions .5 .5 + +@headitem Flag @tab Description +@item GNUTLS_VERIFY_\-DISABLE_CA_SIGN @tab If set a signer does not have to be a certificate authority. This flag should normaly be disabled, unless you know what this means. -@item GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT: +@item GNUTLS_VERIFY_\-ALLOW_X509_V1_CA_CRT @tab Allow only trusted CA certificates that have version 1. This is -safer than GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT, and should be +safer than GNUTLS_VERIFY_\-ALLOW_ANY_X509_V1_CA_CRT, and should be used instead. That way only signers in your trusted list will be allowed to have certificates of version 1. This is the default. -@item GNUTLS_VERIFY_DO_NOT_ALLOW_X509_V1_CA_CRT: +@item GNUTLS_VERIFY_\-DO_NOT_ALLOW_X509_V1_CA_CRT @tab Do not allow trusted version 1 CA certificates. This option is to be used in order consider all V1 certificates as deprecated. -@item GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT: +@item GNUTLS_VERIFY_\-ALLOW_ANY_X509_V1_CA_CRT @tab Allow CA certificates that have version 1 (both root and intermediate). This is dangerous since those haven't the basicConstraints extension. Must be used in combination with -GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT. +GNUTLS_VERIFY_\-ALLOW_X509_V1_CA_CRT. -@item GNUTLS_VERIFY_DO_NOT_ALLOW_SAME: +@item GNUTLS_VERIFY_\-DO_NOT_ALLOW_SAME @tab If a certificate is not signed by anyone trusted but exists in the trusted CA list do not treat it as trusted. -@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2: +@item GNUTLS_VERIFY_\-ALLOW_SIGN_RSA_MD2 @tab Allow certificates to be signed using the old MD2 algorithm. -@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5: +@item GNUTLS_VERIFY_\-ALLOW_SIGN_RSA_MD5 @tab Allow certificates to be signed using the broken MD5 algorithm. -@item GNUTLS_VERIFY_DISABLE_TIME_CHECKS: +@item GNUTLS_VERIFY_\-DISABLE_TIME_CHECKS @tab Disable checking of activation and expiration validity periods of certificate chains. Don't set this unless you understand the security implications. -@item GNUTLS_VERIFY_DISABLE_CRL_CHECKS: +@item GNUTLS_VERIFY_\-DISABLE_CRL_CHECKS @tab Disables checking for validity using certificate revocation lists. -@end table + +@end multitable +@caption{Certificate verification flags.} +@end float Although the verification of a certificate path indicates that the certificate is signed by trusted authority, does not reveal anything @@ -431,7 +452,7 @@ the user to insert the token. All the initialization functions are below. @end itemize Note that due to limitations of @acronym{PKCS} #11 there are issues when multiple libraries -are sharing a module. To avoid this problem GnuTLS uses p11-kit@footnote{http://p11-glue.freedesktop.org/} +are sharing a module. To avoid this problem GnuTLS uses p11-kit@footnote{@url{http://p11-glue.freedesktop.org/}} that provides a middleware to control access to resources over the multiple users. @@ -444,7 +465,7 @@ key on a smart card may be referenced as: @example pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \ manufacturer=EnterSafe;object=test1;objecttype=public;\ -id=32:f1:53:f3:e3:79:90:b0:86:24:14:10:77:ca:5d:ec:2d:15:fa:ed +id=32f153f3e37990b08624141077ca5dec2d15faed @end example while the smart card itself can be referenced as: @@ -680,9 +701,12 @@ signature (2nd preimage resistance). If you are using @funcref{gnutls_certificate_verify_peers2} to verify the certificate chain, you can call -@funcref{gnutls_certificate_set_verify_flags} with the -@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2} or -@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} flag, as in: +@funcref{gnutls_certificate_set_verify_flags} with the flags: +@itemize +@item @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2} +@item @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} +@end itemize +as in the following example: @smallexample gnutls_certificate_set_verify_flags (x509cred, diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi index 632b70ea6a..c30d2be524 100644 --- a/doc/cha-gtls-app.texi +++ b/doc/cha-gtls-app.texi @@ -76,8 +76,9 @@ verbose information on the @acronym{GnuTLS} functions internal flow. When debugging is not required, important issues, such as detected attacks on the protocol still need to be logged. This is provided -by @funcref{gnutls_global_set_audit_log_function}, that uses a logging -function that accepts the detected error message and the corresponding +by the logging function set by +@funcref{gnutls_global_set_audit_log_function}. The set function +accepts the detected error message and the corresponding TLS session. The session information might be used to derive IP addresses or other information about the peer involved. diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi index 3c4a86624e..8a2cf552f5 100644 --- a/doc/cha-intro-tls.texi +++ b/doc/cha-intro-tls.texi @@ -85,9 +85,12 @@ you, call @code{gnutls_transport_set_errno} with the intended errno value instead of setting @code{errno} directly. @acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno -values and returns the corresponding @acronym{GnuTLS} error codes -@code{GNUTLS_E_INTERRUPTED} and @code{GNUTLS_E_AGAIN}. These values -are usually returned by interrupted system calls, or when non blocking +values and returns the corresponding @acronym{GnuTLS} error codes: +@itemize +@item @code{GNUTLS_E_INTERRUPTED} +@item @code{GNUTLS_E_AGAIN} +@end itemize +These values are usually returned by interrupted system calls, or when non blocking IO is used. All @acronym{GnuTLS} functions can be resumed (called again), if any of these error codes is returned. The error codes above refer to the system call, not the @acronym{GnuTLS} function, @@ -158,69 +161,75 @@ just after the handshake protocol has finished. @cindex Symmetric encryption algorithms Confidentiality in the record layer is achieved by using symmetric -block encryption algorithms like @code{3DES}, @code{AES}@footnote{AES, -or Advanced Encryption Standard, is actually the RIJNDAEL algorithm. -This is the algorithm that replaced DES.}, or stream algorithms like -@code{ARCFOUR_128}@footnote{@code{ARCFOUR_128} is a compatible -algorithm with RSA's RC4 algorithm, which is considered to be a trade -secret.}. Ciphers are encryption algorithms that use a single, secret, +block encryption algorithms like @code{3DES}, @code{AES} +or stream algorithms like @code{ARCFOUR_128}. + Ciphers are encryption algorithms that use a single, secret, key to encrypt and decrypt data. Block algorithms in TLS also provide protection against statistical analysis of the data. Thus, if you're using the @acronym{TLS} protocol, a random number of blocks will be appended to data, to prevent eavesdroppers from guessing the actual data size. -Supported cipher algorithms: +The supported in @acronym{GnuTLS} ciphers and MAC algorithms are shown in @ref{tab:ciphers} and +@ref{tab:macs}. -@table @code -@item 3DES_CBC: +@float Table,tab:ciphers +@multitable @columnfractions .30 .70 +@headitem Algorithm @tab Description +@item 3DES_CBC @tab This is the DES block cipher algorithm used with triple encryption (EDE). Has 64 bits block size and is used in CBC mode. -@item ARCFOUR_128: -A fast stream cipher. +@item ARCFOUR_128 @tab +ARCFOUR_128 is a compatible algorithm with RSA's RC4 algorithm, which is considered to be a trade +secret. It is a fast cipher but considered weak today. -@item ARCFOUR_40: +@item ARCFOUR_40 @tab This is the ARCFOUR cipher fed with a 40 bit key, which is considered weak. -@item AES_CBC: +@item AES_CBC @tab AES or RIJNDAEL is the block cipher algorithm that replaces the old DES algorithm. Has 128 bits block size and is used in CBC mode. -@item AES_GCM: +@item AES_GCM @tab This is the AES algorithm in the authenticated encryption GCM mode. This mode combines message authentication and encryption and can be extremely fast on CPUs that support hardware acceleration. -@item CAMELLIA_CBC: +@item CAMELLIA_CBC @tab This is an 128-bit block cipher developed by Mitsubish and NTT. It is one of the approved ciphers of the European NESSIE and Japanese CRYPTREC projects. -@end table - +@end multitable +@caption{Supported ciphers.} +@end float -Supported MAC algorithms: -@table @code -@item MAC_MD5: +@float Table,tab:macs +@multitable @columnfractions .30 .70 +@headitem Algorithm @tab Description +@item MAC_MD5 @tab This is a cryptographic hash algorithm designed by Ron Rivest. Outputs 128 bits of data. -@item MAC_SHA1: +@item MAC_SHA1 @tab A cryptographic hash algorithm designed by NSA. Outputs 160 bits of data. -@item MAC_SHA256: +@item MAC_SHA256 @tab A cryptographic hash algorithm designed by NSA. Outputs 256 bits of data. -@item MAC_AEAD: +@item MAC_AEAD @tab This indicates that an authenticated encryption algorithm, such as GCM, is in use. -@end table +@end multitable +@caption{Supported MAC algorithms.} +@end float + @node Compression algorithms used in the record layer @subsection Compression Algorithms Used in the Record Layer @@ -307,7 +316,7 @@ different incoming IP addresses. To enable the workaround in the @command{gnutls-cli} client or the @command{gnutls-serv} server, for testing of other implementations, use -the following parameter: @option{--priority "NORMAL:%COMPAT"}. +the parameter: @option{--priority "NORMAL:%COMPAT"}. @node The TLS Alert Protocol @@ -392,8 +401,8 @@ To initiate the handshake. @subsection TLS Cipher Suites The Handshake Protocol of @acronym{TLS} negotiates cipher suites of -the form @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA}. The usual cipher -suites contain these parameters: +a special form illustrated by the @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA} cipher suite name. A typical cipher +suite contains these parameters: @itemize @@ -422,45 +431,50 @@ All the supported ciphersuites are shown in @ref{ciphersuites}. In order to specify cipher suite preferences, the previously shown priority functions accept a string that specifies the algorithms to be enabled in a TLS handshake. -That string may contain some high level keyword such as: +That string may contain some high level keyword such as +the keywords in @ref{tab:prio-keywords}. -@table @asis -@item PERFORMANCE: +@float Table,tab:prio-keywords +@multitable @columnfractions .30 .70 +@headitem Keyword @tab Description +@item PERFORMANCE @tab All the "secure" ciphersuites are enabled, limited to 128 bit ciphers and sorted by terms of speed performance. -@item NORMAL: +@item NORMAL @tab Means all "secure" ciphersuites. The 256-bit ciphers are included as a fallback only. The ciphers are sorted by security margin. -@item SECURE128: +@item SECURE128 @tab Means all "secure" ciphersuites of security level 128-bit or more. -@item SECURE192: +@item SECURE192 @tab Means all "secure" ciphersuites of security level 192-bit or more. -@item SUITEB128: +@item SUITEB128 @tab Means all the NSA Suite B cryptography (RFC5430) ciphersuites with an 128 bit security level. -@item SUITEB192: +@item SUITEB192 @tab Means all the NSA Suite B cryptography (RFC5430) ciphersuites with an 192 bit security level. -@item EXPORT: +@item EXPORT @tab Means all ciphersuites are enabled, including the low-security 40 bit ciphers. -@item NONE: +@item NONE @tab Means nothing is enabled. This disables even protocols and compression methods. It should be followed by the algorithms to be enabled. -@end table +@end multitable +@caption{Supported priority string keywords.} +@end float or it might contain special keywords, that will be explained later on. @@ -481,7 +495,9 @@ this string you have to prefix it with "COMP-", protocol versions with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-". All other algorithms don't need a prefix.}. The order with which every algorithm is specified is significant. Similar algorithms specified before others -will take precedence. +will take precedence. The individual algorithms are shown in @ref{tab:prio-algorithms} +and special keywords are in @ref{tab:prio-special}. + Keywords prepended to individual algorithms: @table @asis @@ -494,57 +510,63 @@ appended with an algorithm will add this algorithm. @end table -Individual algorithms: -@table @asis -@item Ciphers: + +@float Table,tab:prio-algorithms +@multitable @columnfractions .30 .70 +@headitem Type @tab Keywords +@item Ciphers @tab AES-128-CBC, AES-256-CBC, AES-128-GCM, CAMELLIA-128-CBC, CAMELLIA-256-CBC, ARCFOUR-128, 3DES-CBC ARCFOUR-40. Catch all name is CIPHER-ALL which will add all the algorithms from NORMAL priority. -@item Key exchange: +@item Key exchange @tab RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS, PSK, DHE-PSK, ECDHE-RSA, ANON-ECDH, ANON-DH, RSA-EXPORT. The Catch all name is KX-ALL which will add all the algorithms from NORMAL priority. -@item MAC: +@item MAC @tab MD5, SHA1, SHA256, AEAD (used with GCM ciphers only). All algorithms from NORMAL priority can be accessed with MAC-ALL. -@item Compression algorithms: +@item Compression algorithms @tab COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL. -@item TLS versions: +@item TLS versions @tab VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1, VERS-TLS1.2. Catch all is VERS-TLS-ALL. -@item Signature algorithms: +@item Signature algorithms @tab SIGN-RSA-SHA1, SIGN-RSA-SHA224, SIGN-RSA-SHA256, SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1, SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5. Catch all is SIGN-ALL. This is only valid for TLS 1.2 and later. -@item Elliptic curves: +@item Elliptic curves @tab CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1, CURVE-SECP521R1. Catch all is CURVE-ALL. -@end table +@end multitable +@caption{The supported priority strings.} +@end float -Special keywords: -@table @asis -@item %COMPAT: +@float Table,tab:prio-special +@multitable @columnfractions .50 .50 +@headitem Keyword @tab Description + +@item %COMPAT @tab will enable compatibility mode. It might mean that violations of the protocols are allowed as long as maximum compatibility with problematic clients and servers is achieved. -@item %DISABLE_SAFE_RENEGOTIATION: +@item %DISABLE_SAFE_RENEGOTIATION @tab will disable safe renegotiation completely. Do not use unless you know what you are doing. Testing purposes only. -@item %UNSAFE_RENEGOTIATION: +@item %UNSAFE_RENEGOTIATION @tab will allow handshakes and rehandshakes without the safe renegotiation extension. Note that for clients this mode is insecure (you may be under attack), and for servers it @@ -552,32 +574,34 @@ will allow insecure clients to connect (which could be fooled by an attacker). Do not use unless you know what you are doing and want maximum compatibility. -@item %PARTIAL_RENEGOTIATION: +@item %PARTIAL_RENEGOTIATION @tab will allow initial handshakes to proceed, but not rehandshakes. This leaves the client vulnerable to attack, and servers will be compatible with non-upgraded clients for initial handshakes. This is currently the default for clients and servers, for compatibility reasons. -@item %SAFE_RENEGOTIATION: +@item %SAFE_RENEGOTIATION @tab will enforce safe renegotiation. Clients and servers will refuse to talk to an insecure peer. Currently this causes operability problems, but is required for full protection. -@item %SSL3_RECORD_VERSION: +@item %SSL3_RECORD_VERSION @tab will use SSL3.0 record version in client hello. This is the default. -@item %LATEST_RECORD_VERSION: +@item %LATEST_RECORD_VERSION @tab will use the latest TLS version record version in client hello. -@item %VERIFY_ALLOW_SIGN_RSA_MD5: +@item %VERIFY_ALLOW_SIGN_RSA_MD5 @tab will allow RSA-MD5 signatures in certificate chains. -@item %VERIFY_ALLOW_X509_V1_CA_CRT: +@item %VERIFY_ALLOW_X509_V1_CA_CRT @tab will allow V1 CAs in chains. -@end table +@end multitable +@caption{Special priority string keywords.} +@end float @node Client Authentication @subsection Client Authentication diff --git a/doc/cha-library.texi b/doc/cha-library.texi index 84e88e8a99..74865237fa 100644 --- a/doc/cha-library.texi +++ b/doc/cha-library.texi @@ -115,7 +115,7 @@ negative number indicates failure, or a situation that some action has to be taken. Thus negative error codes may be fatal or not. Fatal errors terminate the connection immediately and further sends -and receives will be disallowed. An example of a fatal error code is +and receives will be disallowed. Such an example is @code{GNUTLS_E_DECRYPTION_FAILED}. Non-fatal errors may warn about something, i.e., a warning alert was received, or indicate the some action has to be taken. This is the case with the error code @@ -206,10 +206,10 @@ data to the transport layer. @end itemize -Other callback functions such as the one set by -@funcref{gnutls_srp_set_server_credentials_function}, may require more -complicated input, including data to be allocated. These callbacks -should allocate and free memory using the functions shown below. +Other callback functions may require more complicated input and data +to be allocated. Such an example is +@funcref{gnutls_srp_set_server_credentials_function}. +All callbacks should allocate and free memory using the functions shown below. @itemize diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi index e8f7e62503..bbdfade5c3 100644 --- a/doc/cha-programs.texi +++ b/doc/cha-programs.texi @@ -417,7 +417,7 @@ like: @smallexample $ gnutls-cli -p 5556 test.gnutls.org --pskusername jas \ --pskkey 9e32cf7786321a828ef7668f09fb35db \ - --priority NORMAL:+DHE-PSK:+PSK:-RSA:-DHE-RSA + --priority NORMAL:-KX-ALL:+ECDHE-PSK:DHE-PSK:+PSK @end smallexample @menu @@ -450,13 +450,13 @@ Enter password: @end smallexample If the server supports several cipher suites, you may need to force it -to chose PSK by using a cipher priority parameter such as -@option{--priority NORMAL:+PSK:-RSA:-DHE-RSA:-DHE-PSK}. +to chose PSK by using a cipher priority parameter such as in the +example below: @smallexample $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \ --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \ - --priority NORMAL:+DHE-PSK:+PSK + --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK Resolving 'localhost'... Connecting to '127.0.0.1:5556'... - PSK authentication. diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex index aa547665e9..fe7ea2dd60 100755 --- a/doc/scripts/mytexi2latex +++ b/doc/scripts/mytexi2latex @@ -88,9 +88,14 @@ while ($line = ) { $mode = pop(@stack); } else { $line =~ s/\@caption\{/\\caption\{/g; - $line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{3.3cm}|p{3.3cm}|p{4.3cm}|}\n\\hline\n/g; - $line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{2cm}|p{2cm}|p{2cm}|p{2cm}|p{3cm}|}\n\\hline\n/g; - push(@stack, FLOAT_TABLE); + + if ($line =~ m/\@multitable/) { + push(@stack, FLOAT_TABLE); + $line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|}\n\\hline\n/g; + $line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|}\n\\hline\n/g; + $line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|p{$4\\linewidth}|p{$5\\linewidth}|}\n\\hline\n/g; + } + goto multitable; } $prev_mode = $mode; @@ -166,8 +171,8 @@ multitable: } else { $prev_mode = $mode; - $line =~ s/\@iftex/% /g; - $line =~ s/\@end iftex/% /g; + $line =~ s/\@iftex/%c /g; + $line =~ s/\@end iftex/%c /g; $line =~ s/\@anchor (.+)/\\label{$1}/g; $line =~ s/\@anchor\{($spacematch+)\}/\\label{$1}/g; if ($line =~ s/\@subsection (.+)/\\subsection{$1}/g) { @@ -235,11 +240,15 @@ multitable: push(@stack, NORMAL); $mode = TABLE_ITEMIZE; } - if ($line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{3.3cm}|p{3.3cm}|p{4.3cm}|}\n\\hline\n/g) { + if ($line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|}\n\\hline\n/g) { + push(@stack, NORMAL); + $mode = MULTITABLE; + } + if ($line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|}\n\\hline\n/g) { push(@stack, NORMAL); $mode = MULTITABLE; } - if ($line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{2cm}|p{2cm}|p{2cm}|p{2cm}|p{3cm}|}\n\\hline\n/g) { + if ($line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|p{$4\\linewidth}|p{$5\\linewidth}|}\n\\hline\n/g) { push(@stack, NORMAL); $mode = MULTITABLE; } @@ -264,7 +273,7 @@ multitable: if ($verbatim == 0) { $line =~ s/\_/\\_/g; $line =~ s/\~/\\~/g; - $line =~ s/\%/\\%/g; + $line =~ s/\%(?!c)/\\%/g; $line =~ s/\#/\\\#/g; $line =~ s/\@verbatiminclude (.*)/\\examplefile{\.\.\/$1}/g; $line =~ s/\@image\{($match+)\,($match+)\}/\\includegraphics\[width\=$2\]\{\.\.\/$1\.pdf\}/g; -- cgit v1.2.1