br_x509_class Struct Reference

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

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

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