Crypt-Bear
view release on metacpan or search on metacpan
include/bearssl_ssl.h view on Meta::CPAN
* \param len public key point length / X coordinate length.
* \return 1 on success, 0 on error.
*/
uint32_t (*do_keyx)(const br_ssl_client_certificate_class **pctx,
unsigned char *data, size_t *len);
/**
* \brief 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.
*
* \param pctx certificate handler context.
* \param hash_id hash function identifier.
* \param hv_len hash value length (in bytes).
* \param data input/output buffer (hash value, then signature).
* \param len total buffer length (in bytes).
* \return signature length (in bytes) on success, or 0 on error.
*/
size_t (*do_sign)(const br_ssl_client_certificate_class **pctx,
int hash_id, size_t hv_len, unsigned char *data, size_t len);
};
/**
* \brief A single-chain RSA client certificate handler.
*
* This handler uses a single certificate chain, with a RSA
* signature. The list of trust anchor DN is ignored.
*
* Apart from the first field (vtable pointer), its contents are
* opaque and shall not be accessed directly.
*/
typedef struct {
/** \brief Pointer to vtable. */
const br_ssl_client_certificate_class *vtable;
#ifndef BR_DOXYGEN_IGNORE
const br_x509_certificate *chain;
size_t chain_len;
const br_rsa_private_key *sk;
br_rsa_pkcs1_sign irsasign;
#endif
} br_ssl_client_certificate_rsa_context;
/**
* \brief A single-chain EC client certificate handler.
*
* This handler uses a single certificate chain, with a RSA
* signature. The list of trust anchor DN is ignored.
*
* This handler may support both static ECDH, and ECDSA signatures
* (either usage may be selectively disabled).
*
* Apart from the first field (vtable pointer), its contents are
* opaque and shall not be accessed directly.
*/
typedef struct {
/** \brief Pointer to vtable. */
const br_ssl_client_certificate_class *vtable;
#ifndef BR_DOXYGEN_IGNORE
const br_x509_certificate *chain;
size_t chain_len;
const br_ec_private_key *sk;
unsigned allowed_usages;
unsigned issuer_key_type;
const br_multihash_context *mhash;
const br_ec_impl *iec;
br_ecdsa_sign iecdsa;
#endif
} br_ssl_client_certificate_ec_context;
/**
* \brief Context structure for a SSL client.
*
* The first field (called `eng`) is the SSL engine; all functions that
* work on a `br_ssl_engine_context` structure shall take as parameter
* a pointer to that field. The other structure fields are opaque and
* must not be accessed directly.
*/
struct br_ssl_client_context_ {
/**
* \brief The encapsulated engine context.
*/
br_ssl_engine_context eng;
#ifndef BR_DOXYGEN_IGNORE
/*
* Minimum ClientHello length; padding with an extension (RFC
* 7685) is added if necessary to match at least that length.
* Such padding is nominally unnecessary, but it has been used
* to work around some server implementation bugs.
*/
uint16_t min_clienthello_len;
/*
* Bit field for algoithms (hash + signature) supported by the
* server when requesting a client certificate.
*/
uint32_t hashes;
/*
* Server's public key curve.
*/
int server_curve;
/*
* Context for certificate handler.
*/
const br_ssl_client_certificate_class **client_auth_vtable;
/*
* Client authentication type.
*/
unsigned char auth_type;
/*
* Hash function to use for the client signature. This is 0xFF
* if static ECDH is used.
*/
unsigned char hash_id;
/*
* For the core certificate handlers, thus avoiding (in most
include/bearssl_ssl.h view on Meta::CPAN
* Therefore, setting the `server_name` to `NULL` shall be reserved
* to cases where alternate or additional methods are used to ascertain
* that the right server public key is used (e.g. a "known key" model).
*
* If `resume_session` is non-zero and the context was previously used
* then the session parameters may be reused (depending on whether the
* server previously sent a non-empty session ID, and accepts the session
* resumption). The session parameters for session resumption can also
* be set explicitly with `br_ssl_engine_set_session_parameters()`.
*
* On failure, the context is marked as failed, and this function
* returns 0. A possible failure condition is when no initial entropy
* was injected, and none could be obtained from the OS (either OS
* randomness gathering is not supported, or it failed).
*
* \param cc client context.
* \param server_name target server name, or `NULL`.
* \param resume_session non-zero to try session resumption.
* \return 0 on failure, 1 on success.
*/
int br_ssl_client_reset(br_ssl_client_context *cc,
const char *server_name, int resume_session);
/**
* \brief Forget any session in the context.
*
* This means that the next handshake that uses this context will
* necessarily be a full handshake (this applies both to new connections
* and to renegotiations).
*
* \param cc client context.
*/
static inline void
br_ssl_client_forget_session(br_ssl_client_context *cc)
{
cc->eng.session.session_id_len = 0;
}
/**
* \brief Set client certificate chain and key (single RSA case).
*
* This function sets a client certificate chain, that the client will
* send to the server whenever a client certificate is requested. This
* certificate uses an RSA public key; the corresponding private key is
* invoked for authentication. Trust anchor names sent by the server are
* ignored.
*
* The provided chain and private key are linked in the client context;
* they must remain valid as long as they may be used, i.e. normally
* for the duration of the connection, since they might be invoked
* again upon renegotiations.
*
* \param cc SSL client context.
* \param chain client certificate chain (SSL order: EE comes first).
* \param chain_len client chain length (number of certificates).
* \param sk client private key.
* \param irsasign RSA signature implementation (PKCS#1 v1.5).
*/
void br_ssl_client_set_single_rsa(br_ssl_client_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_rsa_private_key *sk, br_rsa_pkcs1_sign irsasign);
/*
* \brief Set the client certificate chain and key (single EC case).
*
* This function sets a client certificate chain, that the client will
* send to the server whenever a client certificate is requested. This
* certificate uses an EC public key; the corresponding private key is
* invoked for authentication. Trust anchor names sent by the server are
* ignored.
*
* The provided chain and private key are linked in the client context;
* they must remain valid as long as they may be used, i.e. normally
* for the duration of the connection, since they might be invoked
* again upon renegotiations.
*
* The `allowed_usages` is a combination of usages, namely
* `BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`. The `BR_KEYTYPE_KEYX`
* value allows full static ECDH, while the `BR_KEYTYPE_SIGN` value
* allows ECDSA signatures. If ECDSA signatures are used, then an ECDSA
* signature implementation must be provided; otherwise, the `iecdsa`
* parameter may be 0.
*
* The `cert_issuer_key_type` value is either `BR_KEYTYPE_RSA` or
* `BR_KEYTYPE_EC`; it is the type of the public key used the the CA
* that issued (signed) the client certificate. That value is used with
* full static ECDH: support of the certificate by the server depends
* on how the certificate was signed. (Note: when using TLS 1.2, this
* parameter is ignored; but its value matters for TLS 1.0 and 1.1.)
*
* \param cc server context.
* \param chain server certificate chain to send.
* \param chain_len chain length (number of certificates).
* \param sk server private key (EC).
* \param allowed_usages allowed private key usages.
* \param cert_issuer_key_type issuing CA's key type.
* \param iec EC core implementation.
* \param iecdsa ECDSA signature implementation ("asn1" format).
*/
void br_ssl_client_set_single_ec(br_ssl_client_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_ec_private_key *sk, unsigned allowed_usages,
unsigned cert_issuer_key_type,
const br_ec_impl *iec, br_ecdsa_sign iecdsa);
/**
* \brief Type for a "translated cipher suite", as an array of two
* 16-bit integers.
*
* The first element is the cipher suite identifier (as used on the wire).
* The second element is the concatenation of four 4-bit elements which
* characterise the cipher suite contents. In most to least significant
* order, these 4-bit elements are:
*
* - Bits 12 to 15: key exchange + server key type
*
* | val | symbolic constant | suite type | details |
* | :-- | :----------------------- | :---------- | :----------------------------------------------- |
* | 0 | `BR_SSLKEYX_RSA` | RSA | RSA key exchange, key is RSA (encryption) |
* | 1 | `BR_SSLKEYX_ECDHE_RSA` | ECDHE_RSA | ECDHE key exchange, key is RSA (signature) |
* | 2 | `BR_SSLKEYX_ECDHE_ECDSA` | ECDHE_ECDSA | ECDHE key exchange, key is EC (signature) |
* | 3 | `BR_SSLKEYX_ECDH_RSA` | ECDH_RSA | Key is EC (key exchange), cert signed with RSA |
* | 4 | `BR_SSLKEYX_ECDH_ECDSA` | ECDH_ECDSA | Key is EC (key exchange), cert signed with ECDSA |
*
* - Bits 8 to 11: symmetric encryption algorithm
*
* | val | symbolic constant | symmetric encryption | key strength (bits) |
* | :-- | :--------------------- | :------------------- | :------------------ |
* | 0 | `BR_SSLENC_3DES_CBC` | 3DES/CBC | 168 |
* | 1 | `BR_SSLENC_AES128_CBC` | AES-128/CBC | 128 |
* | 2 | `BR_SSLENC_AES256_CBC` | AES-256/CBC | 256 |
* | 3 | `BR_SSLENC_AES128_GCM` | AES-128/GCM | 128 |
* | 4 | `BR_SSLENC_AES256_GCM` | AES-256/GCM | 256 |
* | 5 | `BR_SSLENC_CHACHA20` | ChaCha20/Poly1305 | 256 |
*
* - Bits 4 to 7: MAC algorithm
*
* | val | symbolic constant | MAC type | details |
* | :-- | :----------------- | :----------- | :------------------------------------ |
* | 0 | `BR_SSLMAC_AEAD` | AEAD | No dedicated MAC (encryption is AEAD) |
* | 2 | `BR_SSLMAC_SHA1` | HMAC/SHA-1 | Value matches `br_sha1_ID` |
* | 4 | `BR_SSLMAC_SHA256` | HMAC/SHA-256 | Value matches `br_sha256_ID` |
* | 5 | `BR_SSLMAC_SHA384` | HMAC/SHA-384 | Value matches `br_sha384_ID` |
*
* - Bits 0 to 3: hash function for PRF when used with TLS-1.2
*
* | val | symbolic constant | hash function | details |
* | :-- | :----------------- | :------------ | :----------------------------------- |
* | 4 | `BR_SSLPRF_SHA256` | SHA-256 | Value matches `br_sha256_ID` |
* | 5 | `BR_SSLPRF_SHA384` | SHA-384 | Value matches `br_sha384_ID` |
*
* For instance, cipher suite `TLS_RSA_WITH_AES_128_GCM_SHA256` has
* standard identifier 0x009C, and is translated to 0x0304, for, in
* that order: RSA key exchange (0), AES-128/GCM (3), AEAD integrity (0),
* SHA-256 in the TLS PRF (4).
*/
typedef uint16_t br_suite_translated[2];
#ifndef BR_DOXYGEN_IGNORE
/*
* Constants are already documented in the br_suite_translated type.
*/
include/bearssl_ssl.h view on Meta::CPAN
/**
* \brief 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.
*
* \param pctx policy context.
* \param algo_id hash function / algorithm identifier.
* \param data input/output buffer (message/hash, then signature).
* \param hv_len hash value or message length (in bytes).
* \param len total buffer length (in bytes).
* \return signature length (in bytes) on success, or 0 on error.
*/
size_t (*do_sign)(const br_ssl_server_policy_class **pctx,
unsigned algo_id,
unsigned char *data, size_t hv_len, size_t len);
};
/**
* \brief A single-chain RSA policy handler.
*
* This policy context uses a single certificate chain, and a RSA
* private key. The context can be restricted to only signatures or
* only key exchange.
*
* Apart from the first field (vtable pointer), its contents are
* opaque and shall not be accessed directly.
*/
typedef struct {
/** \brief Pointer to vtable. */
const br_ssl_server_policy_class *vtable;
#ifndef BR_DOXYGEN_IGNORE
const br_x509_certificate *chain;
size_t chain_len;
const br_rsa_private_key *sk;
unsigned allowed_usages;
br_rsa_private irsacore;
br_rsa_pkcs1_sign irsasign;
#endif
} br_ssl_server_policy_rsa_context;
/**
* \brief A single-chain EC policy handler.
*
* This policy context uses a single certificate chain, and an EC
* private key. The context can be restricted to only signatures or
* only key exchange.
*
* Due to how TLS is defined, this context must be made aware whether
* the server certificate was itself signed with RSA or ECDSA. The code
* does not try to decode the certificate to obtain that information.
*
* Apart from the first field (vtable pointer), its contents are
* opaque and shall not be accessed directly.
*/
typedef struct {
/** \brief Pointer to vtable. */
const br_ssl_server_policy_class *vtable;
#ifndef BR_DOXYGEN_IGNORE
const br_x509_certificate *chain;
size_t chain_len;
const br_ec_private_key *sk;
unsigned allowed_usages;
unsigned cert_issuer_key_type;
const br_multihash_context *mhash;
const br_ec_impl *iec;
br_ecdsa_sign iecdsa;
#endif
} br_ssl_server_policy_ec_context;
/**
* \brief Class type for a session parameter cache.
*
* Session parameters are saved in the cache with `save()`, and
* retrieved with `load()`. The cache implementation can apply any
* storage and eviction strategy that it sees fit. The SSL server
* context that performs the request is provided, so that its
* functionalities may be used by the implementation (e.g. hash
* functions or random number generation).
*/
typedef struct br_ssl_session_cache_class_ br_ssl_session_cache_class;
struct br_ssl_session_cache_class_ {
/**
* \brief Context size (in bytes).
*/
size_t context_size;
/**
* \brief Record a session.
*
* This callback should record the provided session parameters.
* The `params` structure is transient, so its contents shall
* be copied into the cache. The session ID has been randomly
* generated and always has length exactly 32 bytes.
*
* \param ctx session cache context.
* \param server_ctx SSL server context.
* \param params session parameters to save.
*/
void (*save)(const br_ssl_session_cache_class **ctx,
br_ssl_server_context *server_ctx,
const br_ssl_session_parameters *params);
/**
* \brief Lookup a session in the cache.
*
* The session ID to lookup is in `params` and always has length
* exactly 32 bytes. If the session parameters are found in the
* cache, then the parameters shall be copied into the `params`
* structure. Returned value is 1 on successful lookup, 0
* otherwise.
*
* \param ctx session cache context.
* \param server_ctx SSL server context.
* \param params destination for session parameters.
* \return 1 if found, 0 otherwise.
*/
int (*load)(const br_ssl_session_cache_class **ctx,
br_ssl_server_context *server_ctx,
br_ssl_session_parameters *params);
};
include/bearssl_ssl.h view on Meta::CPAN
const unsigned char *cur_dn;
size_t cur_dn_len;
/*
* Buffer for the hash value computed over all handshake messages
* prior to CertificateVerify, and identifier for the hash function.
*/
unsigned char hash_CV[64];
size_t hash_CV_len;
int hash_CV_id;
/*
* Server-specific implementations.
* (none for now)
*/
#endif
};
/*
* Each br_ssl_server_init_xxx() function sets the list of supported
* cipher suites and used implementations, as specified by the profile
* name 'xxx'. Defined profile names are:
*
* full_rsa all supported algorithm, server key type is RSA
* full_ec all supported algorithm, server key type is EC
* TODO: add other profiles
*
* Naming scheme for "minimal" profiles: min123
*
* -- character 1: key exchange
* r = RSA
* e = ECDHE_RSA
* f = ECDHE_ECDSA
* u = ECDH_RSA
* v = ECDH_ECDSA
* -- character 2: version / PRF
* 0 = TLS 1.0 / 1.1 with MD5+SHA-1
* 2 = TLS 1.2 with SHA-256
* 3 = TLS 1.2 with SHA-384
* -- character 3: encryption
* a = AES/CBC
* d = 3DES/CBC
* g = AES/GCM
* c = ChaCha20+Poly1305
*/
/**
* \brief SSL server profile: full_rsa.
*
* This function initialises the provided SSL server context with
* all supported algorithms and cipher suites that rely on a RSA
* key pair.
*
* \param cc server context to initialise.
* \param chain server certificate chain.
* \param chain_len certificate chain length (number of certificate).
* \param sk RSA private key.
*/
void br_ssl_server_init_full_rsa(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_rsa_private_key *sk);
/**
* \brief SSL server profile: full_ec.
*
* This function initialises the provided SSL server context with
* all supported algorithms and cipher suites that rely on an EC
* key pair.
*
* The key type of the CA that issued the server's certificate must
* be provided, since it matters for ECDH cipher suites (ECDH_RSA
* suites require a RSA-powered CA). The key type is either
* `BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC`.
*
* \param cc server context to initialise.
* \param chain server certificate chain.
* \param chain_len chain length (number of certificates).
* \param cert_issuer_key_type certificate issuer's key type.
* \param sk EC private key.
*/
void br_ssl_server_init_full_ec(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
unsigned cert_issuer_key_type, const br_ec_private_key *sk);
/**
* \brief SSL server profile: minr2g.
*
* This profile uses only TLS_RSA_WITH_AES_128_GCM_SHA256. Server key is
* RSA, and RSA key exchange is used (not forward secure, but uses little
* CPU in the client).
*
* \param cc server context to initialise.
* \param chain server certificate chain.
* \param chain_len certificate chain length (number of certificate).
* \param sk RSA private key.
*/
void br_ssl_server_init_minr2g(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_rsa_private_key *sk);
/**
* \brief SSL server profile: mine2g.
*
* This profile uses only TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256. Server key
* is RSA, and ECDHE key exchange is used. This suite provides forward
* security, with a higher CPU expense on the client, and a somewhat
* larger code footprint (compared to "minr2g").
*
* \param cc server context to initialise.
* \param chain server certificate chain.
* \param chain_len certificate chain length (number of certificate).
* \param sk RSA private key.
*/
void br_ssl_server_init_mine2g(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_rsa_private_key *sk);
/**
* \brief SSL server profile: minf2g.
*
* This profile uses only TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256.
* Server key is EC, and ECDHE key exchange is used. This suite provides
* forward security, with a higher CPU expense on the client and server
* (by a factor of about 3 to 4), and a somewhat larger code footprint
* (compared to "minu2g" and "minv2g").
*
* \param cc server context to initialise.
* \param chain server certificate chain.
* \param chain_len certificate chain length (number of certificate).
* \param sk EC private key.
*/
void br_ssl_server_init_minf2g(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_ec_private_key *sk);
/**
* \brief SSL server profile: minu2g.
*
* This profile uses only TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256.
* Server key is EC, and ECDH key exchange is used; the issuing CA used
* a RSA key.
*
* The "minu2g" and "minv2g" profiles do not provide forward secrecy,
* but are the lightest on the server (for CPU usage), and are rather
* inexpensive on the client as well.
*
* \param cc server context to initialise.
* \param chain server certificate chain.
* \param chain_len certificate chain length (number of certificate).
* \param sk EC private key.
*/
void br_ssl_server_init_minu2g(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_ec_private_key *sk);
/**
* \brief SSL server profile: minv2g.
*
* This profile uses only TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256.
* Server key is EC, and ECDH key exchange is used; the issuing CA used
* an EC key.
*
* The "minu2g" and "minv2g" profiles do not provide forward secrecy,
* but are the lightest on the server (for CPU usage), and are rather
* inexpensive on the client as well.
*
* \param cc server context to initialise.
* \param chain server certificate chain.
* \param chain_len certificate chain length (number of certificate).
* \param sk EC private key.
*/
void br_ssl_server_init_minv2g(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_ec_private_key *sk);
/**
* \brief SSL server profile: mine2c.
*
* This profile uses only TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256.
* Server key is RSA, and ECDHE key exchange is used. This suite
* provides forward security.
*
* \param cc server context to initialise.
* \param chain server certificate chain.
* \param chain_len certificate chain length (number of certificate).
* \param sk RSA private key.
*/
void br_ssl_server_init_mine2c(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_rsa_private_key *sk);
/**
* \brief SSL server profile: minf2c.
*
* This profile uses only TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256.
* Server key is EC, and ECDHE key exchange is used. This suite provides
* forward security.
*
* \param cc server context to initialise.
* \param chain server certificate chain.
* \param chain_len certificate chain length (number of certificate).
* \param sk EC private key.
*/
void br_ssl_server_init_minf2c(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_ec_private_key *sk);
/**
* \brief Get the supported client suites.
*
* This function shall be called only after the ClientHello has been
* processed, typically from the policy engine. The returned array
* contains the cipher suites that are supported by both the client
* and the server; these suites are in client preference order, unless
* the `BR_OPT_ENFORCE_SERVER_PREFERENCES` flag was set, in which case
* they are in server preference order.
*
* The suites are _translated_, which means that each suite is given
* as two 16-bit integers: the standard suite identifier, and its
* translated version, broken down into its individual components,
* as explained with the `br_suite_translated` type.
*
* The returned array is allocated in the context and will be rewritten
* by each handshake.
*
* \param cc server context.
* \param num receives the array size (number of suites).
* \return the translated common cipher suites, in preference order.
*/
static inline const br_suite_translated *
br_ssl_server_get_client_suites(const br_ssl_server_context *cc, size_t *num)
{
*num = cc->client_suites_num;
return cc->client_suites;
}
/**
* \brief Get the hash functions and signature algorithms supported by
* the client.
*
* This value is a bit field:
*
* - If RSA (PKCS#1 v1.5) is supported with hash function of ID `x`,
* then bit `x` is set (hash function ID is 0 for the special MD5+SHA-1,
* or 2 to 6 for the SHA family).
*
* - If ECDSA is supported with hash function of ID `x`, then bit `8+x`
* is set.
*
* - Newer algorithms are symbolic 16-bit identifiers that do not
* represent signature algorithm and hash function separately. If
* the TLS-level identifier is `0x0800+x` for a `x` in the 0..15
* range, then bit `16+x` is set.
*
* "New algorithms" are currently defined only in draft documents, so
* this support is subject to possible change. Right now (early 2017),
* this maps ed25519 (EdDSA on Curve25519) to bit 23, and ed448 (EdDSA
* on Curve448) to bit 24. If the identifiers on the wire change in
* future document, then the decoding mechanism in BearSSL will be
* amended to keep mapping ed25519 and ed448 on bits 23 and 24,
* respectively. Mapping of other new algorithms (e.g. RSA/PSS) is not
* guaranteed yet.
*
* \param cc server context.
* \return the client-supported hash functions and signature algorithms.
*/
include/bearssl_ssl.h view on Meta::CPAN
*
* This is a bit field (bit x is set if curve of ID x is supported).
*
* \param cc server context.
* \return the client-supported elliptic curves.
*/
static inline uint32_t
br_ssl_server_get_client_curves(const br_ssl_server_context *cc)
{
return cc->curves;
}
/**
* \brief Clear the complete contents of a SSL server context.
*
* Everything is cleared, including the reference to the configured buffer,
* implementations, cipher suites and state. This is a preparatory step
* to assembling a custom profile.
*
* \param cc server context to clear.
*/
void br_ssl_server_zero(br_ssl_server_context *cc);
/**
* \brief Set an externally provided policy context.
*
* The policy context's methods are invoked to decide the cipher suite
* and certificate chain, and to perform operations involving the server's
* private key.
*
* \param cc server context.
* \param pctx policy context (pointer to its vtable field).
*/
static inline void
br_ssl_server_set_policy(br_ssl_server_context *cc,
const br_ssl_server_policy_class **pctx)
{
cc->policy_vtable = pctx;
}
/**
* \brief Set the server certificate chain and key (single RSA case).
*
* This function uses a policy context included in the server context.
* It configures use of a single server certificate chain with a RSA
* private key. The `allowed_usages` is a combination of usages, namely
* `BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`; this enables or disables
* the corresponding cipher suites (i.e. `TLS_RSA_*` use the RSA key for
* key exchange, while `TLS_ECDHE_RSA_*` use the RSA key for signatures).
*
* \param cc server context.
* \param chain server certificate chain to send to the client.
* \param chain_len chain length (number of certificates).
* \param sk server private key (RSA).
* \param allowed_usages allowed private key usages.
* \param irsacore RSA core implementation.
* \param irsasign RSA signature implementation (PKCS#1 v1.5).
*/
void br_ssl_server_set_single_rsa(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_rsa_private_key *sk, unsigned allowed_usages,
br_rsa_private irsacore, br_rsa_pkcs1_sign irsasign);
/**
* \brief Set the server certificate chain and key (single EC case).
*
* This function uses a policy context included in the server context.
* It configures use of a single server certificate chain with an EC
* private key. The `allowed_usages` is a combination of usages, namely
* `BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`; this enables or disables
* the corresponding cipher suites (i.e. `TLS_ECDH_*` use the EC key for
* key exchange, while `TLS_ECDHE_ECDSA_*` use the EC key for signatures).
*
* In order to support `TLS_ECDH_*` cipher suites (non-ephemeral ECDH),
* the algorithm type of the key used by the issuing CA to sign the
* server's certificate must be provided, as `cert_issuer_key_type`
* parameter (this value is either `BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC`).
*
* \param cc server context.
* \param chain server certificate chain to send.
* \param chain_len chain length (number of certificates).
* \param sk server private key (EC).
* \param allowed_usages allowed private key usages.
* \param cert_issuer_key_type issuing CA's key type.
* \param iec EC core implementation.
* \param iecdsa ECDSA signature implementation ("asn1" format).
*/
void br_ssl_server_set_single_ec(br_ssl_server_context *cc,
const br_x509_certificate *chain, size_t chain_len,
const br_ec_private_key *sk, unsigned allowed_usages,
unsigned cert_issuer_key_type,
const br_ec_impl *iec, br_ecdsa_sign iecdsa);
/**
* \brief Activate client certificate authentication.
*
* The trust anchor encoded X.500 names (DN) to send to the client are
* provided. A client certificate will be requested and validated through
* the X.509 validator configured in the SSL engine. If `num` is 0, then
* client certificate authentication is disabled.
*
* If the client does not send a certificate, or on validation failure,
* the handshake aborts. Unauthenticated clients can be tolerated by
* setting the `BR_OPT_TOLERATE_NO_CLIENT_AUTH` flag.
*
* The provided array is linked in, not copied, so that pointer must
* remain valid as long as anchor names may be used.
*
* \param cc server context.
* \param ta_names encoded trust anchor names.
* \param num number of encoded trust anchor names.
*/
static inline void
br_ssl_server_set_trust_anchor_names(br_ssl_server_context *cc,
const br_x500_name *ta_names, size_t num)
{
cc->ta_names = ta_names;
cc->tas = NULL;
cc->num_tas = num;
}
/**
* \brief Activate client certificate authentication.
*
* This is a variant for `br_ssl_server_set_trust_anchor_names()`: the
* trust anchor names are provided not as an array of stand-alone names
* (`br_x500_name` structures), but as an array of trust anchors
* (`br_x509_trust_anchor` structures). The server engine itself will
* only use the `dn` field of each trust anchor. This is meant to allow
* defining a single array of trust anchors, to be used here and in the
* X.509 validation engine itself.
*
* The provided array is linked in, not copied, so that pointer must
* remain valid as long as anchor names may be used.
*
* \param cc server context.
* \param tas trust anchors (only names are used).
* \param num number of trust anchors.
*/
static inline void
br_ssl_server_set_trust_anchor_names_alt(br_ssl_server_context *cc,
const br_x509_trust_anchor *tas, size_t num)
{
cc->ta_names = NULL;
cc->tas = tas;
cc->num_tas = num;
}
/**
* \brief Configure the cache for session parameters.
( run in 0.505 second using v1.01-cache-2.11-cpan-ceb78f64989 )