From 0514473421d32a11971d454b459787fe87e9c5ab Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 14 Oct 2022 02:28:41 +0000 Subject: Bring libsbearssl doc up to date. Also fix a typo in sbearssl.h Signed-off-by: Laurent Bercot --- doc/libsbearssl/index.html | 117 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 113 insertions(+), 4 deletions(-) (limited to 'doc/libsbearssl') diff --git a/doc/libsbearssl/index.html b/doc/libsbearssl/index.html index d8ea6ee..64a7c0b 100644 --- a/doc/libsbearssl/index.html +++ b/doc/libsbearssl/index.html @@ -510,6 +510,110 @@ but at least SSL_PROTOCOL=value and SSL_CIPHER=value are transmitted. The function returns 1 if it succeeds and 0 if it fails.

+

X.509 validation with some information extraction

+ +

+ A sbearssl_x509_small_context structure is an implementation of the +br_x509_class type that is a little more powerful than the +br_x509_minimal_context implementation provided by BearSSL: +running a certificate chain through a sbearssl_x509_small_context +validator allows you to get the hash of the End Entity certificate in the +chain, as well as the DN it certifies. +

+ +

void sbearssl_x509_small_init_full (sbearssl_x509_small_context *ctx, br_x509_trust_anchor *btas, size_t n, sbearssl_dn *eedn, uint8_t *eltstatus, char *eehash)

+ +

+ Initializes the validator in *ctx with the list of n +trust anchors pointed to by btas. eehash must point +to a user-supplied buffer of at least 32 bytes, which will contain the +sha256 hash of the EE certificate after validation. eedn must point +to a user-supplied sbearssl_dn structure that will contain the +DN of the end entity after validation. eltstatus must point to a +user-supplied uint8_t, which after validation encodes the status +of DN extraction: bit 7 of eltstatus is set if there was an issue during extraction (in +which case the contents of *eedn are meaningless) and clear if +everything went well, and bits 0 to 6 are set iff the corresponding element +of the DN is present, by increasing order C, ST, L, O, OU and CN. +

+ +

int sbearssl_x509_small_set_tai (sbearssl_x509_small_context *ctx, tai const *t)

+

int sbearssl_x509_small_set_tain (sbearssl_x509_small_context *ctx, tain const *a)

+ +

+ Like their sbearssl_x509_minimal_set_tai and sbearssl_x509_minimal_set_tain +counterparts, but for sbearssl_x509_small_context validators instead of +br_x509_minimal_context ones. +

+ +

Server-side SNI support

+ +

+ A sbearssl_sni_policy_context structure is an implementation of the +br_ssl_server_policy_class type that supports Server Name Identification, +unlike the default br_ssl_server_policy_rsa_context and +br_ssl_server_policy_ec_context implementations provided by BearSSL that +only support a single certificate chain. +

+ +

+ During preparation, the user fills the structure with as many keypairs as they wish; +then at handshake time, depending on the ServerName requested by the client, +the relevant keypair is kept and used, and all the other ones are wiped from memory. +

+ +

void sbearssl_sni_policy_init (sbearssl_sni_policy_context *pol)

+ +

+ Initializes the user-supplied *pol structure. +

+ +

int sbearssl_sni_policy_add_keypair_file (sbearssl_sni_policy_context *pol, char const *servername, char const *certfile, char const *keyfile)

+ +

+ This function reads a PEM-encoded certificate chain in the file certfile, +and a corresponding PEM- or DER-encoded private key in the file keyfile. +It registers them with the *pol structure as the keypair to use if the +client requests the servername ServerName. Wildcards are supported in +servername except on TLDs. If servername is empty, then the +keypair is registered as a default, to use when no ServerName matches (or when +the client doesn't request SNI). +

+ +

+ The function returns 0 on success. It returns a negative value in +case of a system error, in which case errno identifies the +error. It returns a positive value in case of an error returned by +a BearSSL decoder, in which case an appropriate message can be +obtained with the sbearssl_error_str() function. +

+ +

size_t sbearssl_sni_policy_nkeypairs (sbearssl_sni_policy_context const *pol)

+ +

+ Returns the number of keypairs currently registered with *pol. +

+ +

void sbearssl_sctx_init_full_generic (br_ssl_server_context *sc)

+ +

+ Not directly related to SNI support, but complementary to it. This function is +a high-level function missing from BearSSL: it fully initializes a +br_ssl_server_context structure, registering all the cipher suites +and all the hashes provided by BearSSL with a good degradation order, +supporting TLS 1.0 to TLS 1.2, etc. What it doesn't set: the engine buffer, +the certificate policy, the optional engine flags, and the optional client +certificate validation. +

+ +

void sbearssl_sctx_set_policy_sni (br_ssl_server_context *sc, sbearssl_sni_policy_context *pol)

+ +

+ Registers *pol as the certificate policy for the *sc +server context. This tells BearSSL that the handshake will support SNI +and use the keypairs registered with *pol. +

+

Running the TLS/SSL engine (internal function for both clients and servers)

void sbearssl_run (br_ssl_engine_context *ctx, int *fds, tain const *tto, uint32_t options, unsigned int verbosity, sbearssl_handshake_cb_t_ref cb, sbearssl_handshake_cb_context_t *cbarg)

@@ -572,6 +676,13 @@ SSL/TLS connection closed cleanly, the process exits 0.

Initializing and running the engine

+

+ The following functions are high-level interfaces and rely on all the +functions described above. They're the core of the +s6-tlsc-io and +s6-tlsd-io programs. +

+

void sbearssl_client_init_and_run (int *fds, tain const *tto, uint32_t preoptions, uint32_t options, unsigned int verbosity, char const *servername, sbearssl_handshake_cb_t_ref cb, unsigned int notif)

@@ -606,8 +717,7 @@ the network. the CERTFILE and KEYFILE environment variables are read, they must contain the path to a valid client certificate and private key (else the process exits 96); this certificate is then provided to the -server for client authentication. This feature is currently -unsupported and will not work; leave that bit clear for now. +server for client authentication.

  • options : a bitfield, which will be passed to sbearssl_run(). @@ -636,8 +746,7 @@ completed.
    • argument is required. The CERTFILE and KEYFILE environment variables are mandatory, they point to the server's certificate and private key. It is only necessary to set CADIR or CAFILE when bit -0 of preoptions is set (this functionality is supported server-side), -in which case client authentication will be +0 of preoptions is set, in which case client authentication will be requested, and a list of trust anchors (read from either the directory in CADIR or the PEM file in CAFILE) will be used to verify the client certificate. -- cgit v1.2.3