![]() |
wget2 2.0.0
|
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) |
void wget_ssl_set_config_string | ( | int | key, |
const char * | value | ||
) |
[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):
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
. 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_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_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.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.
void wget_ssl_set_config_object | ( | int | key, |
void * | value | ||
) |
[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.
void wget_ssl_set_config_int | ( | int | key, |
int | value | ||
) |
[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):
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_DIRECTORY
or WGET_SSL_CA_FILE
.WGET_SSL_CERT_FILE
. The certificate and the private key supplied must both be of the same format.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.
[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):
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_DIRECTORY
or WGET_SSL_CA_FILE
.WGET_SSL_CERT_FILE
. The certificate and the private key supplied must both be of the same format.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.
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.
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.
int wget_ssl_open | ( | wget_tcp * | tcp | ) |
[in] | tcp | A TCP connection (see wget_tcp_init()) |
WGET_E_SUCCESS
on success or an error code (WGET_E_*
) on failureRun 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().
void wget_ssl_close | ( | void ** | session | ) |
[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.
ssize_t wget_ssl_read_timeout | ( | void * | session, |
char * | buf, | ||
size_t | count, | ||
int | timeout | ||
) |
[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) |
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.
ssize_t wget_ssl_write_timeout | ( | void * | session, |
const char * | buf, | ||
size_t | count, | ||
int | timeout | ||
) |
[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) |
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.
void wget_ssl_set_stats_callback_tls | ( | wget_tls_stats_callback * | fn, |
void * | ctx | ||
) |
[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
void wget_ssl_set_stats_callback_ocsp | ( | wget_ocsp_stats_callback * | fn, |
void * | ctx | ||
) |
[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