@item @code{KX_SRP_RSA}, @code{KX_SRP_DSS}
@tab @code{CRD_SRP}
-@tab @code{CRD_CERTIFICATE}
+@tab @code{CRD_CERTIFICATE}, @code{CRD_SRP}
@item @code{KX_SRP}
@tab @code{CRD_SRP}
validation error (see @ref{Verifying X.509 certificate paths}), it means
that somewhere in the certificate chain there is a certificate signed
using @code{RSA-MD2} or @code{RSA-MD5}. These two digital signature
-algorithms are considered broken, so GnuTLS fail when attempting to
-verify the certificate. In some situations, it may be useful to be
+algorithms are considered broken, so GnuTLS fails verifying
+the certificate. In some situations, it may be useful to be
able to verify the certificate chain anyway, assuming an attacker did
not utilize the fact that these signatures algorithms are broken.
This section will give help on how to achieve that.
-First, it is important to know that you do not have to enable any of
+It is important to know that you do not have to enable any of
the flags discussed here to be able to use trusted root CA
-certificates signed using @code{RSA-MD2} or @code{RSA-MD5}. The only
-attack today is that it is possible to generate certificates with
-colliding signatures (collision resistance); you cannot generate a
-certificate that has the same signature as an already existing
-signature (2nd preimage resistance).
+certificates self-signed using @code{RSA-MD2} or @code{RSA-MD5}. The
+certificates in the trusted list are considered trusted irrespective
+of the signature.
If you are using @funcref{gnutls_certificate_verify_peers2} to verify the
certificate chain, you can call
to not use the flags by default, and only fall back to using them
after warning the user. If you wish to inspect the certificate chain
yourself, you can use @funcref{gnutls_certificate_get_peers} to extract
-the raw server's certificate chain, then use
-@funcref{gnutls_x509_crt_import} to parse each of the certificates, and
-then use @funcref{gnutls_x509_crt_get_signature_algorithm} to find out the
+the raw server's certificate chain, @funcref{gnutls_x509_crt_list_import} to parse each of the certificates, and
+then @funcref{gnutls_x509_crt_get_signature_algorithm} to find out the
signing algorithm used for each certificate. If any of the
intermediary certificates are using @code{GNUTLS_SIGN_RSA_MD2} or
@code{GNUTLS_SIGN_RSA_MD5}, you could present a warning.
functions.
@showfuncdesc{gnutls_record_send}
+
@showfuncdesc{gnutls_record_recv}
In DTLS it is adviceable to use the extended receive
A helper function is available to check whether data
to be read are pending in a @acronym{GnuTLS} session.
-This is the equivalent in POSIX systems to using @code{select}
-for data waiting to be read by @code{recv}.
+This is the equivalent of @code{select} in @acronym{POSIX} systems.
@showfuncdesc{gnutls_record_check_pending}
@subsection Simple datagram @acronym{TLS} client example
This is a client that uses @acronym{UDP} to connect to a
-server. This is the @acronym{DTLS} equivalent to
-@ref{Simple client example with X.509 certificate support} above.
+server. This is the @acronym{DTLS} equivalent to the example
+in @ref{Simple client example with X.509 certificate support}.
@verbatiminclude examples/ex-client-udp.c
the majority of deployed servers out there. We will reconsider this
default behavior in the future when more servers have been upgraded.
Note that it is easy to configure clients to always require the safe
-renegotiation extension from servers (see below on the
-@code{%SAFE_RENEGOTIATION} priority string).
+renegotiation extension from servers.
To modify the default behavior, we have introduced some new priority
-strings. The priority strings can be used by applications
-(@funcref{gnutls_priority_set}) and end users (e.g., @code{--priority}
-parameter to @code{gnutls-cli} and @code{gnutls-serv}).
-
+strings (see @ref{Priority Strings}).
The @code{%UNSAFE_RENEGOTIATION} priority string permits
(re-)handshakes even when the safe renegotiation extension was not
negotiated. The default behavior is @code{%PARTIAL_RENEGOTIATION} that will
@section Selecting cryptographic key sizes
@cindex Key sizes
-In TLS, since a lot of algorithms are involved, it is not easy to set
+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}.
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.
-Note however that the values suggested here are nothing more than an
+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
#include <config.h>
#endif
-#include <getpass.h>
-
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
+#include <getpass.h> /* for getpass() */
/* A TLS client that loads the certificate and key.
*/
* gnutls_record_check_pending:
* @session: is a #gnutls_session_t structure.
*
- * This function checks if there are any data to receive in the gnutls
- * buffers.
+ * This function checks if there are unread data
+ * in the gnutls buffers. If the return value is
+ * non-zero the next call to gnutls_record_recv()
+ * is guarranteed not to block.
*
- * Returns: The size of that data or 0.
+ * Returns: Returns the size of the data or zero.
**/
size_t
gnutls_record_check_pending (gnutls_session_t session)
* certificate corresponds to the given public key.
*
* If the buffer provided is not long enough to hold the output, then
- * *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
+ * *output_data_size is updated and %GNUTLS_E_SHORT_MEMORY_BUFFER will
* be returned. The output will normally be a SHA-1 hash output,
* which is 20 bytes.
*
* This function will export the certificate to DER or PEM format.
*
* If the buffer provided is not long enough to hold the output, then
- * *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
+ * *output_data_size is updated and %GNUTLS_E_SHORT_MEMORY_BUFFER will
* be returned.
*
* If the structure is PEM encoded, it will have a header
* certificate corresponds to the given public key.
*
* If the buffer provided is not long enough to hold the output, then
- * *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
+ * *output_data_size is updated and %GNUTLS_E_SHORT_MEMORY_BUFFER will
* be returned. The output will normally be a SHA-1 hash output,
* which is 20 bytes.
*
* This function will verify the given signed data, using the
* parameters from the certificate.
*
- * Returns: In case of a verification failure
- * %GNUTLS_E_PK_SIG_VERIFY_FAILED is returned, and a positive code
- * on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
+ * negative error value (%GNUTLS_E_PK_SIG_VERIFY_FAILED in verification failure).
*
* Since: 2.12.0
**/
* This function will verify the given signed data, using the
* parameters from the certificate.
*
- * Returns: In case of a verification failure
- * %GNUTLS_E_PK_SIG_VERIFY_FAILED is returned, and a positive code
- * on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
+ * negative error value (%GNUTLS_E_PK_SIG_VERIFY_FAILED in verification failure).
*
* Since: 3.0.0
**/
* This function will verify the given signed digest, using the
* parameters from the certificate.
*
- * Returns: In case of a verification failure %GNUTLS_E_PK_SIG_VERIFY_FAILED
- * is returned, and a positive code on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
+ * negative error value (%GNUTLS_E_PK_SIG_VERIFY_FAILED in verification failure).
*
* Since: 2.12.0
**/
* This function will read the certifcate and the signed data to
* determine the hash algorithm used to generate the signature.
*
- * Returns: the 0 if the hash algorithm is found. A negative error code is
- * returned on error.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
+ * negative error value.
*
* Since: 2.12.0
**/
* have been initiated using gnutls_handshake(). @how should be one
* of %GNUTLS_SHUT_RDWR, %GNUTLS_SHUT_WR.
*
- * In case of %GNUTLS_SHUT_RDWR then the TLS connection gets
+ * In case of %GNUTLS_SHUT_RDWR the TLS session gets
* terminated and further receives and sends will be disallowed. If
- * the return value is zero you may continue using the connection.
- * %GNUTLS_SHUT_RDWR actually sends an alert containing a close
+ * the return value is zero you may continue using the underlying
+ * transport layer. %GNUTLS_SHUT_RDWR sends an alert containing a close
* request and waits for the peer to reply with the same message.
*
- * In case of %GNUTLS_SHUT_WR then the TLS connection gets terminated
+ * In case of %GNUTLS_SHUT_WR the TLS session gets terminated
* and further sends will be disallowed. In order to reuse the
* connection you should wait for an EOF from the peer.
* %GNUTLS_SHUT_WR sends an alert containing a close request.
*
* Note that not all implementations will properly terminate a TLS
* connection. Some of them, usually for performance reasons, will
- * terminate only the underlying transport layer, thus causing a
- * transmission error to the peer. This error cannot be
- * distinguished from a malicious party prematurely terminating the
- * session, thus this behavior is not recommended.
+ * terminate only the underlying transport layer, and thus not
+ * distinguishing between a malicious party prematurely terminating
+ * the connection and normal termination.
*
* This function may also return %GNUTLS_E_AGAIN or
* %GNUTLS_E_INTERRUPTED; cf. gnutls_record_get_direction().
projects / thirdparty / gnutls.git / commitdiff
