wget2: SSL/TLS engine

| wget2 2.0.0

- Main Page
- Modules
- Data Structures
- Files

Data Structures | Functions
SSL/TLS engine

## Data Structures
struct | wget_ocsp_stats_data
struct | wget_tls_stats_data
struct | config
struct | session_context

## Functions
void | wget_ssl_set_config_string (int key, const char *value)
void | wget_ssl_set_config_object (int key, void *value)
void | wget_ssl_set_config_int (int key, int value)
void | wget_ssl_init (void)
void | wget_ssl_deinit (void)
int | wget_ssl_open (wget_tcp *tcp)
void | wget_ssl_close (void **session)
ssize_t | wget_ssl_read_timeout (void *session, char *buf, size_t count, int timeout)
ssize_t | wget_ssl_write_timeout (void *session, const char *buf, size_t count, int timeout)
void | wget_ssl_set_stats_callback_tls (wget_tls_stats_callback *fn, void *ctx)
void | wget_ssl_set_stats_callback_ocsp (wget_ocsp_stats_callback *fn, void *ctx)

## Detailed Description

## Function Documentation

## ◆ wget_ssl_set_config_string()

void wget_ssl_set_config_string | ( | int | key,
|  | const char * | value
| ) |  |

Parameters

  [in] | key | An identifier for the config parameter (starting with `WGET_SSL_`) to set
  [in] | value | The value for the config parameter (a NULL-terminated string)

Set a configuration parameter, as a string.

The following parameters accept a string as their value (`key` can have any of those values):

- WGET_SSL_SECURE_PROTOCOL: A string describing which SSL/TLS version should be used. It can have either an arbitrary value, or one of the following fixed values (case does not matter):
  - "SSL": SSLv3 will be used. Warning: this protocol is insecure and should be avoided.
  - "TLSv1": TLS 1.0 will be used.
  - "TLSv1_1": TLS 1.1 will be used.
  - "TLSv1_2": TLS 1.2 will be used.
  - "TLSv1_3": TLS 1.3 will be used.
  - "AUTO": Let the TLS library decide.
  - "PFS": Let the TLS library decide, but make sure only forward-secret ciphers are used.

An arbitrary string can also be supplied (an string that's different from any of the previous ones). If that's the case the string will be directly taken as the priority string and sent to the library. Priority strings provide the greatest flexibility, but have a library-specific syntax. A GnuTLS priority string will not work if your libwget has been compiled with OpenSSL, for instance.

- WGET_SSL_CA_DIRECTORY: A path to the directory where the root certificates will be taken from for server cert validation. Every file of that directory is expected to contain an X.509 certificate, encoded in PEM format. If the string "system" is specified, the system's default directory will be used. The default value is "system". Certificates get loaded in wget_ssl_init().
- WGET_SSL_CA_FILE: A path to a file containing a single root certificate. This will be used to validate the server's certificate chain. This option can be used together with `WGET_SSL_CA_DIRECTORY`. The certificate can be in either PEM or DER format. The format is specified in the `WGET_SSL_CA_TYPE` option (see wget_ssl_set_config_int()).
- WGET_SSL_CERT_FILE: Set the client certificate. It will be used for client authentication if the server requests it. It can be in either PEM or DER format. The format is specified in the `WGET_SSL_CERT_TYPE` option (see wget_ssl_set_config_int()). The `WGET_SSL_KEY_FILE` option specifies the private key corresponding to the cert's public key. If `WGET_SSL_KEY_FILE` is not set, then the private key is expected to be in the same file as the certificate.
- WGET_SSL_KEY_FILE: Set the private key corresponding to the client certificate specified in `WGET_SSL_CERT_FILE`. It can be in either PEM or DER format. The format is specified in the `WGET_SSL_KEY_TYPE` option (see wget_ssl_set_config_int()). IF `WGET_SSL_CERT_FILE` is not set, then the certificate is expected to be in the same file as the private key.
- WGET_SSL_CRL_FILE: Sets a CRL (Certificate Revocation List) file which will be used to verify client and server certificates. A CRL file is a black list that contains the serial numbers of the certificates that should not be treated as valid. Whenever a client or a server presents a certificate in the TLS handshake whose serial number is contained in the CRL, the handshake will be immediately aborted. The CRL file must be in PEM format.
- WGET_SSL_OCSP_SERVER: Set the URL of the OCSP server that will be used to validate certificates. OCSP is a protocol by which a server is queried to tell whether a given certificate is valid or not. It's an approach contrary to that used by CRLs. While CRLs are black lists, OCSP takes a white list approach where a certificate can be checked for validity. Whenever a client or server presents a certificate in a TLS handshake, the provided URL will be queried (using OCSP) to check whether that certificate is valid or not. If the server responds the certificate is not valid, the handshake will be immediately aborted.
- WGET_SSL_ALPN: Sets the ALPN string to be sent to the remote host. ALPN is a TLS extension (RFC 7301) that allows both the server and the client to signal which application-layer protocols they support (HTTP/2, QUIC, etc.). That information can then be used for the server to ultimately decide which protocol will be used on top of TLS.

An invalid value for `key` will not harm the operation of TLS, but will cause a complain message to be printed to the error log stream.

## ◆ wget_ssl_set_config_object()

void wget_ssl_set_config_object | ( | int | key,
|  | void * | value
| ) |  |

Parameters

  [in] | key | An identifier for the config parameter (starting with `WGET_SSL_`) to set
  [in] | value | The value for the config parameter (a pointer)

Set a configuration parameter, as a libwget object.

The following parameters expect an already initialized libwget object as their value.

- WGET_SSL_OCSP_CACHE: This option takes a pointer to a wget_ocsp_db structure as an argument. Such a pointer is returned when initializing the OCSP cache with wget_ocsp_db_init(). The cache is used to store OCSP responses locally and avoid querying the OCSP server repeatedly for the same certificate.
- WGET_SSL_SESSION_CACHE: This option takes a pointer to a wget_tls_session_db structure. Such a pointer is returned when initializing the TLS session cache with wget_tls_session_db_init(). This option thus sets the handle to the TLS session cache that will be used to store TLS sessions. The TLS session cache is used to support TLS session resumption. It stores the TLS session parameters derived from a previous TLS handshake (most importantly the session identifier and the master secret) so that there's no need to run the handshake again the next time we connect to the same host. This is useful as the handshake is an expensive process.
- WGET_SSL_HPKP_CACHE: Set the HPKP cache to be used to verify known HPKP pinned hosts. This option takes a pointer to a wget_hpkp_db structure. Such a pointer is returned when initializing the HPKP cache with wget_hpkp_db_init(). HPKP is a HTTP-level protocol that allows the server to "pin" its present and future X.509 certificate fingerprints, to support rapid certificate change in the event that the higher level root CA gets compromised (RFC 7469).

## ◆ wget_ssl_set_config_int()

void wget_ssl_set_config_int | ( | int | key,
|  | int | value
| ) |  |

Parameters

  [in] | key | An identifier for the config parameter (starting with `WGET_SSL_`)
  [in] | value | The value for the config parameter

Set a configuration parameter, as an integer.

These are the parameters that can be set (`key` can have any of these values):

- WGET_SSL_CHECK_CERTIFICATE: whether certificates should be verified (1) or not (0)
- WGET_SSL_CHECK_HOSTNAME: whether or not to check if the certificate's subject field matches the peer's hostname. This check is done according to the rules in RFC 6125 and typically involves checking whether the hostname and the common name (CN) field of the subject match.
- WGET_SSL_PRINT_INFO: whether or not information should be printed about the established SSL/TLS handshake (negotiated ciphersuites, certificates, etc.). The default is no (0).

The following three options all can take either `WGET_SSL_X509_FMT_PEM` (to specify the PEM format) or `WGET_SSL_X509_FMT_DER` (for the DER format). The default in for all of them is `WGET_SSL_X509_FMT_PEM`.

- WGET_SSL_CA_TYPE: Specifies what's the format of the root CA certificate(s) supplied with either `WGET_SSL_CA_DIRECTORY` or `WGET_SSL_CA_FILE`.
- WGET_SSL_CERT_TYPE: Specifies what's the format of the certificate file supplied with `WGET_SSL_CERT_FILE`. The certificate and the private key supplied must both be of the same format.
- WGET_SSL_KEY_TYPE: Specifies what's the format of the private key file supplied with `WGET_SSL_KEY_FILE`. The private key and the certificate supplied must both be of the same format.

The following two options control OCSP queries. These don't affect the CRL set with `WGET_SSL_CRL_FILE`, if any. If both CRLs and OCSP are enabled, both will be used.

- WGET_SSL_OCSP: whether or not OCSP should be used. The default is yes (1).
- WGET_SSL_OCSP_STAPLING: whether or not OCSP stapling should be used. The default is yes (1).
- WGET_SSL_OCSP_NONCE: whether or not an OCSP nonce should be sent in the request. The default is yes (1). If a nonce was sent in the request, the OCSP verification will fail if the response nonce doesn't match. However if the response does not include a nonce extension, verification will be allowed to continue. The OCSP nonce extension is not a critical one.
- WGET_SSL_OCSP_DATE: Reject the OCSP response if it's older than 3 days.

Parameters

  [in] | key | An identifier for the config parameter (starting with `WGET_SSL_`)
  [in] | value | The value for the config parameter

Set a configuration parameter, as an integer.

These are the parameters that can be set (`key` can have any of these values):

- WGET_SSL_CHECK_CERTIFICATE: whether certificates should be verified (1) or not (0)
- WGET_SSL_CHECK_HOSTNAME: whether or not to check if the certificate's subject field matches the peer's hostname. This check is done according to the rules in RFC 6125 and typically involves checking whether the hostname and the common name (CN) field of the subject match.
- WGET_SSL_PRINT_INFO: whether or not information should be printed about the established SSL/TLS handshake (negotiated ciphersuites, certificates, etc.). The default is no (0).

The following three options all can take either `WGET_SSL_X509_FMT_PEM` (to specify the PEM format) or `WGET_SSL_X509_FMT_DER` (for the DER format). The default in for all of them is `WGET_SSL_X509_FMT_PEM`.

- WGET_SSL_CA_TYPE: Specifies what's the format of the root CA certificate(s) supplied with either `WGET_SSL_CA_DIRECTORY` or `WGET_SSL_CA_FILE`.
- WGET_SSL_CERT_TYPE: Specifies what's the format of the certificate file supplied with `WGET_SSL_CERT_FILE`. The certificate and the private key supplied must both be of the same format.
- WGET_SSL_KEY_TYPE: Specifies what's the format of the private key file supplied with `WGET_SSL_KEY_FILE`. The private key and the certificate supplied must both be of the same format.

The following two options control OCSP queries. These don't affect the CRL set with `WGET_SSL_CRL_FILE`, if any. If both CRLs and OCSP are enabled, both will be used.

- WGET_SSL_OCSP: whether or not OCSP should be used. The default is yes (1).
- WGET_SSL_OCSP_STAPLING: whether or not OCSP stapling should be used. The default is yes (1).

## ◆ wget_ssl_init()

void wget_ssl_init | ( | void |  | ) |

Initialize the SSL/TLS engine as a client.

This function assumes the caller is an SSL client connecting to a server. The functions wget_ssl_open(), wget_ssl_close() and wget_ssl_deinit() can be called after this.

This is where the root certificates get loaded from the folder specified in the `WGET_SSL_CA_DIRECTORY` parameter. If any of the files in that folder cannot be loaded for whatever reason, that file will be silently skipped without harm (a message will be printed to the debug log stream).

CLRs and private keys and their certificates are also loaded here.

On systems with automatic library constructors/destructors, this function is thread-safe. On other systems it is not thread-safe.

This function may be called several times. Only the first call really takes action.

## ◆ wget_ssl_deinit()

void wget_ssl_deinit | ( | void |  | ) |

Deinitialize the SSL/TLS engine, after it has been initialized with wget_ssl_init().

This function unloads everything that was loaded in wget_ssl_init().

On systems with automatic library constructors/destructors, this function is thread-safe. On other systems it is not thread-safe.

This function may be called several times. Only the last deinit really takes action.

## ◆ wget_ssl_open()

int wget_ssl_open | ( | wget_tcp * | tcp | ) |

Parameters

  [in] | tcp | A TCP connection (see wget_tcp_init())

Returns
  `WGET_E_SUCCESS` on success or an error code (`WGET_E_*`) on failure

Run an SSL/TLS handshake.

This functions establishes an SSL/TLS tunnel (performs an SSL/TLS handshake) over an active TCP connection. A pointer to the (internal) SSL/TLS session context can be found in `tcp->ssl_session` after successful execution of this function. This pointer has to be passed to wget_ssl_close() to close the SSL/TLS tunnel.

If the handshake cannot be completed in the specified timeout for the provided TCP connection this function fails and returns `WGET_E_TIMEOUT`. You can set the timeout with wget_tcp_set_timeout().

## ◆ wget_ssl_close()

void wget_ssl_close | ( | void ** | session | ) |

Parameters

  [in] | session | The SSL/TLS session (a pointer to it), which is located at the `ssl_session` field of the TCP connection (see wget_ssl_open()).

Close an active SSL/TLS tunnel, which was opened with wget_ssl_open().

The underlying TCP connection is kept open.

## ◆ wget_ssl_read_timeout()

ssize_t wget_ssl_read_timeout | ( | void * | session,
|  | char * | buf,
|  | size_t | count,
|  | int | timeout
| ) |  |

Parameters

  [in] | session | An opaque pointer to the SSL/TLS session (obtained with wget_ssl_open() or wget_ssl_server_open())
  [in] | buf | Destination buffer where the read data will be placed
  [in] | count | Length of the buffer `buf`
  [in] | timeout | The amount of time to wait until data becomes available (in milliseconds)

Returns
  The number of bytes read, or a negative value on error.

Read data from the SSL/TLS tunnel.

This function will read at most `count` bytes, which will be stored in the buffer `buf`.

The `timeout` parameter tells how long to wait until some data becomes available to read. A `timeout` value of zero causes this function to return immediately, whereas a negative value will cause it to wait indefinitely. This function returns the number of bytes read, which may be zero if the timeout elapses without any data having become available.

If a rehandshake is needed, this function does it automatically and tries to read again.

## ◆ wget_ssl_write_timeout()

ssize_t wget_ssl_write_timeout | ( | void * | session,
|  | const char * | buf,
|  | size_t | count,
|  | int | timeout
| ) |  |

Parameters

  [in] | session | An opaque pointer to the SSL/TLS session (obtained with wget_ssl_open() or wget_ssl_server_open())
  [in] | buf | Buffer with the data to be sent
  [in] | count | Length of the buffer `buf`
  [in] | timeout | The amount of time to wait until data can be sent to the wire (in milliseconds)

Returns
  The number of bytes written, or a negative value on error.

Send data through the SSL/TLS tunnel.

This function will write `count` bytes from `buf`.

The `timeout` parameter tells how long to wait until data can be finally sent over the SSL/TLS tunnel. A `timeout` value of zero causes this function to return immediately, whereas a negative value will cause it to wait indefinitely. This function returns the number of bytes sent, which may be zero if the timeout elapses before any data could be sent.

If a rehandshake is needed, this function does it automatically and tries to write again.

## ◆ wget_ssl_set_stats_callback_tls()

void wget_ssl_set_stats_callback_tls | ( | wget_tls_stats_callback * | fn,
|  | void * | ctx
| ) |  |

Parameters

  [in] | fn | A `wget_ssl_stats_callback_tls_t` callback function to receive TLS statistics data
  [in] | ctx | Context data given to `fn`

Set callback function to be called when TLS statistics are available

## ◆ wget_ssl_set_stats_callback_ocsp()

void wget_ssl_set_stats_callback_ocsp | ( | wget_ocsp_stats_callback * | fn,
|  | void * | ctx
| ) |  |

Parameters

  [in] | fn | A `wget_ssl_stats_callback_ocsp_t` callback function to receive OCSP statistics data
  [in] | ctx | Context data given to `fn`

Set callback function to be called when OCSP statistics are available