br_ssl_client_certificate_class Struct Reference

Class type for a certificate handler (client side). More...

Data Fields
size_t	context_size
	Context size (in bytes). More...
void(*	start_name_list )(const br_ssl_client_certificate_class **pctx)
	Begin reception of a list of trust anchor names. This is called while parsing the incoming CertificateRequest. More...
void(*	start_name )(const br_ssl_client_certificate_class **pctx, size_t len)
	Begin reception of a new trust anchor name. More...
void(*	append_name )(const br_ssl_client_certificate_class **pctx, const unsigned char *data, size_t len)
	Receive some more bytes for the current trust anchor name. More...
void(*	end_name )(const br_ssl_client_certificate_class **pctx)
	End current trust anchor name. More...
void(*	end_name_list )(const br_ssl_client_certificate_class **pctx)
	End list of trust anchor names. More...
void(*	choose )(const br_ssl_client_certificate_class **pctx, const br_ssl_client_context *cc, uint32_t auth_types, br_ssl_client_certificate *choices)
	Select client certificate and algorithms. More...
uint32_t(*	do_keyx )(const br_ssl_client_certificate_class **pctx, unsigned char *data, size_t *len)
	Perform key exchange (client part). More...
size_t(*	do_sign )(const br_ssl_client_certificate_class **pctx, int hash_id, size_t hv_len, unsigned char *data, size_t len)
	Perform a signature (client authentication). More...

Detailed Description

Class type for a certificate handler (client side).

A certificate handler selects a client certificate chain to send to the server, upon explicit request from that server. It receives the list of trust anchor DN from the server, and supported types of certificates and signatures, and returns the chain to use. It is also invoked to perform the corresponding private key operation (a signature, or an ECDH computation).

The SSL client engine will first push the trust anchor DN with start_name_list(), start_name(), append_name(), end_name() and end_name_list(). Then it will call choose(), to select the actual chain (and signature/hash algorithms). Finally, it will call either do_sign() or do_keyx(), depending on the algorithm choices.

Field Documentation

append_name

void(* br_ssl_client_certificate_class::append_name) (const br_ssl_client_certificate_class **pctx, const unsigned char *data, size_t len)

Receive some more bytes for the current trust anchor name.

The provided reference (data) points to a transient buffer they may be reused as soon as this function returns. The chunk length (len) is never zero.

Parameters

pctx	certificate handler context.
data	anchor name chunk.
len	anchor name chunk length (in bytes).

choose

void(* br_ssl_client_certificate_class::choose) (const br_ssl_client_certificate_class **pctx, const br_ssl_client_context *cc, uint32_t auth_types, br_ssl_client_certificate *choices)

Select client certificate and algorithms.

This callback function shall fill the provided choices structure with the selected algorithms and certificate chain. The hash_id, chain and chain_len fields must be set. If the client cannot or does not wish to send a certificate, then it shall set chain to NULL and chain_len to 0.

The auth_types parameter describes the authentication types, signature algorithms and hash functions that are supported by both the client context and the server, and compatible with the current protocol version. This is a bit field with the following contents:

• If RSA signatures with hash function x are supported, then bit x is set.
• If ECDSA signatures with hash function x are supported, then bit 8+x is set.
• If static ECDH is supported, with a RSA-signed certificate, then bit 16 is set.
• If static ECDH is supported, with an ECDSA-signed certificate, then bit 17 is set.

Notes:

• When using TLS 1.0 or 1.1, the hash function for RSA signatures is always the special MD5+SHA-1 (id 0), and the hash function for ECDSA signatures is always SHA-1 (id 2).
• When using TLS 1.2, the list of hash functions is trimmed down to include only hash functions that the client context can support. The actual server list can be obtained with br_ssl_client_get_server_hashes(); that list may be used to select the certificate chain to send to the server.

Parameters

pctx	certificate handler context.
cc	SSL client context.
auth_types	supported authentication types and algorithms.
choices	destination structure for the policy choices.

context_size

size_t br_ssl_client_certificate_class::context_size

Context size (in bytes).

do_keyx

uint32_t(* br_ssl_client_certificate_class::do_keyx) (const br_ssl_client_certificate_class **pctx, unsigned char *data, size_t *len)

Perform key exchange (client part).

This callback is invoked in case of a full static ECDH key exchange:

• the cipher suite uses ECDH_RSA or ECDH_ECDSA;
• the server requests a client certificate;
• the client has, and sends, a client certificate that uses an EC key in the same curve as the server's key, and chooses static ECDH (the hash_id field in the choice structure was set to -1).

In that situation, this callback is invoked to compute the client-side ECDH: the provided data (of length *len bytes) is the server's public key point (as decoded from its certificate), and the client shall multiply that point with its own private key, and write back the X coordinate of the resulting point in the same buffer, starting at offset 0. The *len value shall be modified to designate the actual length of the X coordinate.

The callback must uphold the following:

• If the input array does not have the proper length for an encoded curve point, then an error (0) shall be reported.
• If the input array has the proper length, then processing MUST be constant-time, even if the data is not a valid encoded point.
• This callback MUST check that the input point is valid.

Returned value is 1 on success, 0 on error.

Parameters

pctx	certificate handler context.
data	server public key point.
len	public key point length / X coordinate length.

Returns

1 on success, 0 on error.

do_sign

size_t(* br_ssl_client_certificate_class::do_sign) (const br_ssl_client_certificate_class **pctx, int hash_id, size_t hv_len, unsigned char *data, size_t len)

Perform a signature (client authentication).

This callback is invoked when a client certificate was sent, and static ECDH is not used. It shall compute a signature, using the client's private key, over the provided hash value (which is the hash of all previous handshake messages).

On input, the hash value to sign is in data, of size hv_len; the involved hash function is identified by hash_id. The signature shall be computed and written back into data; the total size of that buffer is len bytes.

This callback shall verify that the signature length does not exceed len bytes, and abstain from writing the signature if it does not fit.

For RSA signatures, the hash_id may be 0, in which case this is the special header-less signature specified in TLS 1.0 and 1.1, with a 36-byte hash value. Otherwise, normal PKCS#1 v1.5 signatures shall be computed.

For ECDSA signatures, the signature value shall use the ASN.1 based encoding.

Returned value is the signature length (in bytes), or 0 on error.

Parameters

pctx	certificate handler context.
hash_id	hash function identifier.
hv_len	hash value length (in bytes).
data	input/output buffer (hash value, then signature).
len	total buffer length (in bytes).

Returns

signature length (in bytes) on success, or 0 on error.

end_name

void(* br_ssl_client_certificate_class::end_name) (const br_ssl_client_certificate_class **pctx)

End current trust anchor name.

This function is called when all the encoded anchor name data has been provided.

Parameters

pctx	certificate handler context.

end_name_list

void(* br_ssl_client_certificate_class::end_name_list) (const br_ssl_client_certificate_class **pctx)

End list of trust anchor names.

This function is called when all the anchor names in the CertificateRequest message have been obtained.

Parameters

pctx	certificate handler context.

start_name

void(* br_ssl_client_certificate_class::start_name) (const br_ssl_client_certificate_class **pctx, size_t len)

Begin reception of a new trust anchor name.

The total encoded name length is provided; it is less than 65535 bytes.

Parameters

pctx	certificate handler context.
len	encoded name length (in bytes).

start_name_list

void(* br_ssl_client_certificate_class::start_name_list) (const br_ssl_client_certificate_class **pctx)

Begin reception of a list of trust anchor names. This is called while parsing the incoming CertificateRequest.

Parameters

pctx	certificate handler context.

---

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

• bearssl_ssl.h