@menu
* Client examples::
* Server examples::
+* More advanced client and servers::
* OCSP example::
* Miscellaneous examples::
@end menu
implemented by another example.
@menu
-* Simple client example with X.509 certificate support::
-* Simple client example with SSH-style certificate verification::
-* Simple client example with anonymous authentication::
-* Simple Datagram TLS client example::
-* Obtaining session information::
-* Using a callback to select the certificate to use::
-* Verifying a certificate::
+* Client example with X.509 certificate support::
+* Datagram TLS client example::
* Client using a smart card with TLS::
* Client with Resume capability example::
-* Simple client example with SRP authentication::
-* Legacy client example with X.509 certificate support::
-* Simple client example in C++::
-* Helper functions for TCP connections::
-* Helper functions for UDP connections::
+* Client example with SSH-style certificate verification::
@end menu
-@node Simple client example with X.509 certificate support
-@subsection Simple client example with @acronym{X.509} certificate support
+@node Client example with X.509 certificate support
+@subsection Client example with @acronym{X.509} certificate support
@anchor{ex-verify}
Let's assume now that we want to create a TCP client which
@verbatiminclude examples/ex-client-x509.c
-@node Simple client example with SSH-style certificate verification
-@subsection Simple client example with SSH-style certificate verification
+
+@node Datagram TLS client example
+@subsection 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 the TLS example
+with X.509 certificates.
+
+@verbatiminclude examples/ex-client-dtls.c
+
+
+@node Client using a smart card with TLS
+@subsection Using a smart card with TLS
+@anchor{ex-pkcs11-client}
+@cindex Smart card example
+
+This example will demonstrate how to load keys and certificates
+from a smart-card or any other @acronym{PKCS} #11 token, and
+use it in a TLS connection. The difference between this and the
+@ref{Client example with X.509 certificate support} is that the
+client keys are provided as PKCS #11 URIs instead of files.
+
+@verbatiminclude examples/ex-cert-select-pkcs11.c
+
+
+@node Client with Resume capability example
+@subsection Client with resume capability example
+@anchor{ex-resume-client}
+
+This is a modification of the simple client example. Here we
+demonstrate the use of session resumption. The client tries to connect
+once using @acronym{TLS}, close the connection and then try to
+establish a new connection using the previously negotiated data.
+
+@verbatiminclude examples/ex-client-resume.c
+
+
+
+
+@node Client example with SSH-style certificate verification
+@subsection Client example with SSH-style certificate verification
This is an alternative verification function that will use the
X.509 certificate authorities for verification, but also assume an
@verbatiminclude examples/ex-verify-ssh.c
-@node Simple client example with anonymous authentication
-@subsection Simple client example with anonymous authentication
+@node Server examples
+@section Server examples
+
+This section contains examples of @acronym{TLS} and @acronym{SSL}
+servers, using @acronym{GnuTLS}.
+
+@menu
+* Echo server with X.509 authentication::
+* DTLS echo server with X.509 authentication::
+@end menu
+
+@node Echo server with X.509 authentication
+@subsection Echo server with @acronym{X.509} authentication
+
+This example is a very simple echo server which supports
+@acronym{X.509} authentication.
+
+@verbatiminclude examples/ex-serv-x509.c
+
+
+@node DTLS echo server with X.509 authentication
+@subsection DTLS echo server with @acronym{X.509} authentication
+
+This example is a very simple echo server using Datagram TLS and
+@acronym{X.509} authentication.
+
+@verbatiminclude examples/ex-serv-dtls.c
+
+
+
+
+@node More advanced client and servers
+@section More advanced client and servers
+
+This section has various, more advanced topics in client and servers.
+
+@menu
+* Client example with anonymous authentication::
+* Using a callback to select the certificate to use::
+* Obtaining session information::
+* Advanced certificate verification example::
+* Client example with SRP authentication::
+* Legacy client example with X.509 certificate support::
+* Client example in C++::
+* Echo server with SRP authentication::
+* Echo server with anonymous authentication::
+* Helper functions for TCP connections::
+* Helper functions for UDP connections::
+@end menu
+
+@node Client example with anonymous authentication
+@subsection Client example with anonymous authentication
The simplest client using TLS is the one that doesn't do any
authentication. This means no external certificates or passwords are
@verbatiminclude examples/ex-client-anon.c
+@node Using a callback to select the certificate to use
+@subsection Using a callback to select the certificate to use
-@node Simple Datagram TLS client example
-@subsection Simple datagram @acronym{TLS} client example
+There are cases where a client holds several certificate and key
+pairs, and may not want to load all of them in the credentials
+structure. The following example demonstrates the use of the
+certificate selection callback.
-This is a client that uses @acronym{UDP} to connect to a
-server. This is the @acronym{DTLS} equivalent to the TLS example
-with X.509 certificates.
+@verbatiminclude examples/ex-cert-select.c
-@verbatiminclude examples/ex-client-dtls.c
@node Obtaining session information
@subsection Obtaining session information
@verbatiminclude examples/ex-session-info.c
-@node Using a callback to select the certificate to use
-@subsection Using a callback to select the certificate to use
-
-There are cases where a client holds several certificate and key
-pairs, and may not want to load all of them in the credentials
-structure. The following example demonstrates the use of the
-certificate selection callback.
-@verbatiminclude examples/ex-cert-select.c
-@node Verifying a certificate
-@subsection Verifying a certificate
+@node Advanced certificate verification example
+@subsection Advanced certificate verification
@anchor{ex-verify2}
An example is listed below which uses the high level verification
-functions to verify a given certificate list.
+functions to verify a given certificate chain against a set of CAs
+and CRLs.
@verbatiminclude examples/ex-verify.c
-@node Client using a smart card with TLS
-@subsection Using a smart card with TLS
-@anchor{ex-pkcs11-client}
-@cindex Smart card example
-
-This example will demonstrate how to load keys and certificates
-from a smart-card or any other @acronym{PKCS} #11 token, and
-use it in a TLS connection.
-
-@verbatiminclude examples/ex-cert-select-pkcs11.c
-
-
-@node Client with Resume capability example
-@subsection Client with resume capability example
-@anchor{ex-resume-client}
-
-This is a modification of the simple client example. Here we
-demonstrate the use of session resumption. The client tries to connect
-once using @acronym{TLS}, close the connection and then try to
-establish a new connection using the previously negotiated data.
-
-@verbatiminclude examples/ex-client-resume.c
-
-
-@node Simple client example with SRP authentication
-@subsection Simple client example with @acronym{SRP} authentication
+@node Client example with SRP authentication
+@subsection Client example with @acronym{SRP} authentication
The following client is a very simple @acronym{SRP} @acronym{TLS}
client which connects to a server and authenticates using a
@anchor{ex-verify-legacy}
For applications that need to maintain compatibility with the GnuTLS 3.1.x
-library, this client example is identical to @ref{Simple client example with X.509 certificate support}
+library, this client example is identical to @ref{Client example with X.509 certificate support}
but utilizes APIs that were available in GnuTLS 3.1.4.
@verbatiminclude examples/ex-client-x509-3.1.c
-
-@node Simple client example in C++
-@subsection Simple client example using the C++ API
+@node Client example in C++
+@subsection Client example using the C++ API
The following client is a simple example of a client client utilizing
the GnuTLS C++ API.
@verbatiminclude examples/ex-cxx.cpp
-@node Helper functions for TCP connections
-@subsection Helper functions for TCP connections
-
-Those helper function abstract away TCP connection handling from the
-other examples. It is required to build some examples.
-
-@verbatiminclude examples/tcp.c
-
-@node Helper functions for UDP connections
-@subsection Helper functions for UDP connections
-
-The UDP helper functions abstract away UDP connection handling from the
-other examples. It is required to build the examples using UDP.
-
-@verbatiminclude examples/udp.c
-
-@node Server examples
-@section Server examples
-
-This section contains examples of @acronym{TLS} and @acronym{SSL}
-servers, using @acronym{GnuTLS}.
-
-@menu
-* Echo server with X.509 authentication::
-* Echo server with SRP authentication::
-* Echo server with anonymous authentication::
-* DTLS echo server with X.509 authentication::
-@end menu
-
-@node Echo server with X.509 authentication
-@subsection Echo server with @acronym{X.509} authentication
-
-This example is a very simple echo server which supports
-@acronym{X.509} authentication.
-
-@verbatiminclude examples/ex-serv-x509.c
@node Echo server with SRP authentication
@subsection Echo server with @acronym{SRP} authentication
@verbatiminclude examples/ex-serv-srp.c
+
@node Echo server with anonymous authentication
@subsection Echo server with anonymous authentication
@verbatiminclude examples/ex-serv-anon.c
-@node DTLS echo server with X.509 authentication
-@subsection DTLS echo server with @acronym{X.509} authentication
-This example is a very simple echo server using Datagram TLS and
-@acronym{X.509} authentication.
-@verbatiminclude examples/ex-serv-dtls.c
+@node Helper functions for TCP connections
+@subsection Helper functions for TCP connections
+
+Those helper function abstract away TCP connection handling from the
+other examples. It is required to build some examples.
+
+@verbatiminclude examples/tcp.c
+
+@node Helper functions for UDP connections
+@subsection Helper functions for UDP connections
+
+The UDP helper functions abstract away UDP connection handling from the
+other examples. It is required to build the examples using UDP.
+
+@verbatiminclude examples/udp.c
+
@node OCSP example
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
+#include <assert.h>
#include <gnutls/gnutls.h>
-/* Those functions are defined in other examples.
- */
extern void check_alert(gnutls_session_t session, int ret);
extern int tcp_connect(void);
extern void tcp_close(int sd);
+/* A very basic TLS client, with X.509 authentication and server certificate
+ * verification as well as session resumption.
+ *
+ * Note that error recovery is minimal for simplicity.
+ */
+
+#define CHECK(x) assert((x)>=0)
+
#define MAX_BUF 1024
-#define CAFILE "/etc/ssl/certs/ca-certificates.crt"
#define MSG "GET / HTTP/1.0\r\n\r\n"
int main(void)
/* variables used in session resuming
*/
int t;
- char *session_data = NULL;
- size_t session_data_size = 0;
-
- gnutls_global_init();
+ gnutls_datum_t sdata;
- /* X509 stuff */
- gnutls_certificate_allocate_credentials(&xcred);
+ /* for backwards compatibility with gnutls < 3.3.0 */
+ CHECK(gnutls_global_init());
- gnutls_certificate_set_x509_trust_file(xcred, CAFILE,
- GNUTLS_X509_FMT_PEM);
+ CHECK(gnutls_certificate_allocate_credentials(&xcred));
+ CHECK(gnutls_certificate_set_x509_system_trust(xcred));
for (t = 0; t < 2; t++) { /* connect 2 times to the server */
sd = tcp_connect();
- gnutls_init(&session, GNUTLS_CLIENT);
+ CHECK(gnutls_init(&session, GNUTLS_CLIENT));
- gnutls_priority_set_direct(session,
- "PERFORMANCE:!ARCFOUR-128",
- NULL);
+ CHECK(gnutls_server_name_set(session, GNUTLS_NAME_DNS,
+ "my_host_name",
+ strlen("my_host_name")));
+ gnutls_session_set_verify_cert(session, "my_host_name", 0);
+
+ CHECK(gnutls_set_default_priority(session));
+
+ gnutls_transport_set_int(session, sd);
+ gnutls_handshake_set_timeout(session,
+ GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE,
xcred);
if (t > 0) {
/* if this is not the first time we connect */
- gnutls_session_set_data(session, session_data,
- session_data_size);
- free(session_data);
+ CHECK(gnutls_session_set_data(session, sdata.data,
+ sdata.size));
+ gnutls_free(sdata.data);
}
- gnutls_transport_set_int(session, sd);
- gnutls_handshake_set_timeout(session,
- GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
-
/* Perform the TLS handshake
*/
do {
}
if (t == 0) { /* the first time we connect */
- /* get the session data size */
- gnutls_session_get_data(session, NULL,
- &session_data_size);
- session_data = malloc(session_data_size);
-
- /* put session data to the session variable */
- gnutls_session_get_data(session, session_data,
- &session_data_size);
-
- } else { /* the second time we connect */
+ /* get the session data */
+ CHECK(gnutls_session_get_data2(session, &sdata));
+ } else { /* the second time we connect */
/* check if we actually resumed the previous session */
if (gnutls_session_is_resumed(session) != 0) {
}
}
- /* This function was defined in a previous example
- */
- /* print_info(session); */
-
gnutls_record_send(session, MSG, strlen(MSG));
ret = gnutls_record_recv(session, buffer, MAX_BUF);
*/
int print_info(gnutls_session_t session)
{
- const char *tmp;
gnutls_credentials_type_t cred;
gnutls_kx_algorithm_t kx;
- int dhe, ecdh;
+ int dhe, ecdh, group;
+ char *desc;
+
+ /* get a description of the session connection, protocol,
+ * cipher/key exchange */
+ desc = gnutls_session_get_desc(session);
+ if (desc != NULL) {
+ printf("- Session: %s\n", desc);
+ }
dhe = ecdh = 0;
- /* print the key exchange's algorithm name
- */
kx = gnutls_kx_get(session);
- tmp = gnutls_kx_get_name(kx);
- printf("- Key Exchange: %s\n", tmp);
/* Check the authentication type used and switch
* to the appropriate.
*/
cred = gnutls_auth_get_type(session);
switch (cred) {
- case GNUTLS_CRD_IA:
- printf("- TLS/IA session\n");
- break;
-
-
#ifdef ENABLE_SRP
case GNUTLS_CRD_SRP:
printf("- SRP session with username %s\n",
* print some information about it.
*/
print_x509_certificate_info(session);
-
+ break;
+ default:
+ break;
} /* switch */
- if (ecdh != 0)
- printf("- Ephemeral ECDH using curve %s\n",
- gnutls_ecc_curve_get_name(gnutls_ecc_curve_get
- (session)));
- else if (dhe != 0)
- printf("- Ephemeral DH using prime of %d bits\n",
- gnutls_dh_get_prime_bits(session));
-
- /* print the protocol's name (ie TLS 1.0)
- */
- tmp =
- gnutls_protocol_get_name(gnutls_protocol_get_version(session));
- printf("- Protocol: %s\n", tmp);
-
- /* print the certificate type of the peer.
- * ie X.509
- */
- tmp =
- gnutls_certificate_type_get_name(gnutls_certificate_type_get
- (session));
-
- printf("- Certificate Type: %s\n", tmp);
-
- /* print the compression algorithm (if any)
- */
- tmp = gnutls_compression_get_name(gnutls_compression_get(session));
- printf("- Compression: %s\n", tmp);
-
- /* print the name of the cipher used.
- * ie 3DES.
- */
- tmp = gnutls_cipher_get_name(gnutls_cipher_get(session));
- printf("- Cipher: %s\n", tmp);
-
- /* Print the MAC algorithms name.
- * ie SHA1
- */
- tmp = gnutls_mac_get_name(gnutls_mac_get(session));
- printf("- MAC: %s\n", tmp);
+ /* read the negotiated group - if any */
+ group = gnutls_group_get(session);
+ if (group != 0) {
+ printf("- Negotiated group %s\n",
+ gnutls_group_get_name(group));
+ } else {
+ if (ecdh != 0)
+ printf("- Ephemeral ECDH using curve %s\n",
+ gnutls_ecc_curve_get_name(gnutls_ecc_curve_get
+ (session)));
+ else if (dhe != 0)
+ printf("- Ephemeral DH using prime of %d bits\n",
+ gnutls_dh_get_prime_bits(session));
+ }
return 0;
}
projects / thirdparty / gnutls.git / commitdiff
