BearSSL: br_ssl_server_policy_class Struct Reference

BearSSL

Data Fields
br_ssl_server_policy_class Struct Reference

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

`#include <bearssl_ssl.h>`

## 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