br_ssl_server_policy_class Struct Reference

Class type for a policy handler (server side). More...

Data Fields
size_t	context_size
	Context size (in bytes). More...
int(*	choose )(const br_ssl_server_policy_class **pctx, const br_ssl_server_context *cc, br_ssl_server_choices *choices)
	Select algorithms and certificates for this connection. More...
uint32_t(*	do_keyx )(const br_ssl_server_policy_class **pctx, unsigned char *data, size_t *len)
	Perform key exchange (server part). More...
size_t(*	do_sign )(const br_ssl_server_policy_class **pctx, unsigned algo_id, unsigned char *data, size_t hv_len, size_t len)
	Perform a signature (for a ServerKeyExchange message). More...

Detailed Description

Class type for a policy handler (server side).

A policy handler selects the policy parameters for a connection (cipher suite and other algorithms, and certificate chain to send to the client); it also performs the server-side computations involving its permanent private key.

The SSL server engine will invoke first choose(), once the ClientHello message has been received, then either do_keyx() do_sign(), depending on the cipher suite.

Field Documentation

choose

int(* br_ssl_server_policy_class::choose) (const br_ssl_server_policy_class **pctx, const br_ssl_server_context *cc, br_ssl_server_choices *choices)

Select algorithms and certificates for this connection.

This callback function shall fill the provided choices structure with the policy choices for this connection. This entails selecting the cipher suite, hash function for signing the ServerKeyExchange (applicable only to ECDHE cipher suites), and certificate chain to send.

The callback receives a pointer to the server context that contains the relevant data. In particular, the functions br_ssl_server_get_client_suites(), br_ssl_server_get_client_hashes() and br_ssl_server_get_client_curves() can be used to obtain the cipher suites, hash functions and elliptic curves supported by both the client and server, respectively. The br_ssl_engine_get_version() and br_ssl_engine_get_server_name() functions yield the protocol version and requested server name (SNI), respectively.

This function may modify its context structure (pctx) in arbitrary ways to keep track of its own choices.

This function shall return 1 if appropriate policy choices could be made, or 0 if this connection cannot be pursued.

Parameters

pctx	policy context.
cc	SSL server context.
choices	destination structure for the policy choices.

Returns

1 on success, 0 on error.

context_size

size_t br_ssl_server_policy_class::context_size

Context size (in bytes).

do_keyx

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

Perform key exchange (server part).

This callback is invoked to perform the server-side cryptographic operation for a key exchange that is not ECDHE. This callback uses the private key.

For RSA key exchange, the provided data (of length *len bytes) shall be decrypted with the server's private key, and the 48-byte premaster secret copied back to the first 48 bytes of data.

• The caller makes sure that *len is at least 59 bytes.
• This callback MUST check that the provided length matches that of the key modulus; it shall report an error otherwise.
• If the length matches that of the RSA key modulus, then processing MUST be constant-time, even if decryption fails, or the padding is incorrect, or the plaintext message length is not exactly 48 bytes.
• This callback needs not check the two first bytes of the obtained pre-master secret (the caller will do that).
• If an error is reported (0), then what the callback put in the first 48 bytes of data is unimportant (the caller will use random bytes instead).

For ECDH key exchange, the provided data (of length *len bytes) is the elliptic curve point from the client. The callback shall multiply it with its private key, and store the resulting X coordinate in data, starting at offset 0, and set *len to the length of the X coordinate.

• 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	policy context.
data	key exchange data from the client.
len	key exchange data length (in bytes).

Returns

1 on success, 0 on error.

do_sign

size_t(* br_ssl_server_policy_class::do_sign) (const br_ssl_server_policy_class **pctx, unsigned algo_id, unsigned char *data, size_t hv_len, size_t len)

Perform a signature (for a ServerKeyExchange message).

This callback function is invoked for ECDHE cipher suites. On input, the hash value or message to sign is in data, of size hv_len; the involved hash function or algorithm is identified by algo_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.

The algo_id value matches that which was written in the choices structures by the choose() callback. This will be one of the following:

• 0xFF00 + id for a hash function identifier id. In that case, the data buffer contains a hash value already computed over the data that is to be signed, of length hv_len. The id may be 0 to designate the special MD5+SHA-1 concatenation (old-style RSA signing).
• Another value, lower than 0xFF00. The data buffer then contains the raw, non-hashed data to be signed (concatenation of the client and server randoms and ECDH parameters). The callback is responsible to apply any relevant hashing as part of the signing process.

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

Parameters

pctx	policy context.
algo_id	hash function / algorithm identifier.
data	input/output buffer (message/hash, then signature).
hv_len	hash value or message length (in bytes).
len	total buffer length (in bytes).

Returns

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

---

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

• bearssl_ssl.h