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
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
@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
@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.
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}.
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}
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
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
@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
@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.
@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:
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,
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.
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,
@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
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
@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
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.
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
@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
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
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
@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
@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
@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.
$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;
} 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) {
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;
}
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;
projects / thirdparty / gnutls.git / commitdiff
