BearSSL: br_x509_class Struct Reference

BearSSL

Loading...
Searching...
No Matches
Data Fields
br_x509_class Struct Reference

Class type for an X.509 engine. More...

`#include <bearssl_x509.h>`

## Data Fields
size_t | context_size
| X.509 context size, in bytes.
void(* | start_chain )(const br_x509_class **ctx, const char *server_name)
| Start a new chain.
void(* | start_cert )(const br_x509_class **ctx, uint32_t length)
| Start a new certificate.
void(* | append )(const br_x509_class **ctx, const unsigned char *buf, size_t len)
| Receive some bytes for the current certificate.
void(* | end_cert )(const br_x509_class **ctx)
| Finish the current certificate.
unsigned(* | end_chain )(const br_x509_class **ctx)
| Finish the chain.
const br_x509_pkey *(* | get_pkey )(const br_x509_class *const *ctx, unsigned *usages)
| Get the resulting end-entity public key.

## Detailed Description

Class type for an X.509 engine.

A certificate chain validation uses a caller-allocated context, which contains the running state for that validation. Methods are called in due order:

- `start_chain()` is called at the start of the validation.
- Certificates are processed one by one, in SSL order (end-entity comes first). For each certificate, the following methods are called:
  - `start_cert()` at the beginning of the certificate.
  - `append()` is called zero, one or more times, to provide the certificate (possibly in chunks).
  - `end_cert()` at the end of the certificate.
- `end_chain()` is called when the last certificate in the chain was processed.
- `get_pkey()` is called after chain processing, if the chain validation was successful.

A context structure may be reused; the `start_chain()` method shall ensure (re)initialisation.

## Field Documentation

## ◆ append

void(* br_x509_class::append) (const br_x509_class **ctx, const unsigned char *buf, size_t len)

Receive some bytes for the current certificate.

This function may be called several times in succession for a given certificate. The caller guarantees that for each call, `len` is not zero, and the sum of all chunk lengths for a certificate matches the total certificate length which was provided in the previous `start_cert()` call.

If the new certificate is empty (no byte at all) then this function won't be called at all.

Parameters

  ctx | validation context.
  buf | certificate data chunk.
  len | certificate data chunk length (in bytes).

## ◆ context_size

size_t br_x509_class::context_size

X.509 context size, in bytes.

## ◆ end_cert

void(* br_x509_class::end_cert) (const br_x509_class **ctx)

Finish the current certificate.

This function is called when the end of the current certificate is reached.

Parameters

  ctx | validation context.

## ◆ end_chain

unsigned(* br_x509_class::end_chain) (const br_x509_class **ctx)

Finish the chain.

This function is called at the end of the chain. It shall return either 0 if the validation was successful, or a non-zero error code. The `BR_ERR_X509_*` constants are error codes, though other values may be possible.

Parameters

  ctx | validation context.

Returns
  0 on success, or a non-zero error code.

## ◆ get_pkey

const br_x509_pkey *(* br_x509_class::get_pkey) (const br_x509_class *const *ctx, unsigned *usages)

Get the resulting end-entity public key.

The decoded public key is returned. The returned pointer may be valid only as long as the context structure is unmodified, i.e. it may cease to be valid if the context is released or reused.

This function may return `NULL` if the validation failed. However, returning a public key does not mean that the validation was wholly successful; some engines may return a decoded public key even if the chain did not end on a trusted anchor.

If validation succeeded and `usage` is not `NULL`, then `*usage` is filled with a combination of `BR_KEYTYPE_SIGN` and/or `BR_KEYTYPE_KEYX` that specifies the validated key usage types. It is the caller's responsibility to check that value against the intended use of the public key.

Parameters

  ctx | validation context.

Returns
  the end-entity public key, or `NULL`.

## ◆ start_cert

void(* br_x509_class::start_cert) (const br_x509_class **ctx, uint32_t length)

Start a new certificate.

Parameters

  ctx | validation context.
  length | new certificate length (in bytes).

## ◆ start_chain

void(* br_x509_class::start_chain) (const br_x509_class **ctx, const char *server_name)

Start a new chain.

This method shall set the vtable (first field) of the context structure.

The `server_name`, if not `NULL`, will be considered as a fully qualified domain name, to be matched against the `dNSName` elements of the end-entity certificate's SAN extension (if there is no SAN, then the Common Name from the subjectDN will be used). If `server_name` is `NULL` then no such matching is performed.

Parameters

  ctx | validation context.
  server_name | server name to match (or `NULL`).

The documentation for this struct was generated from the following file:

- bearssl_x509.h