BearSSL: bearssl_prf.h File Reference

BearSSL

Loading...
Searching...
No Matches
Data Structures | Typedefs | Functions
bearssl_prf.h File Reference
Include dependency graph for bearssl_prf.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | br_tls_prf_seed_chunk
| Type for a seed chunk. More...

## Typedefs
typedef void(* | br_tls_prf_impl) (void *dst, size_t len, const void *secret, size_t secret_len, const char *label, size_t seed_num, const br_tls_prf_seed_chunk *seed)

## Functions
void | br_tls10_prf (void *dst, size_t len, const void *secret, size_t secret_len, const char *label, size_t seed_num, const br_tls_prf_seed_chunk *seed)
| PRF implementation for TLS 1.0 and 1.1.
void | br_tls12_sha256_prf (void *dst, size_t len, const void *secret, size_t secret_len, const char *label, size_t seed_num, const br_tls_prf_seed_chunk *seed)
| PRF implementation for TLS 1.2, with SHA-256.
void | br_tls12_sha384_prf (void *dst, size_t len, const void *secret, size_t secret_len, const char *label, size_t seed_num, const br_tls_prf_seed_chunk *seed)
| PRF implementation for TLS 1.2, with SHA-384.

## Detailed Description

# The TLS PRF

The "PRF" is the pseudorandom function used internally during the SSL/TLS handshake, notably to expand negotiated shared secrets into the symmetric encryption keys that will be used to process the application data.

TLS 1.0 and 1.1 define a PRF that is based on both MD5 and SHA-1. This is implemented by the `br_tls10_prf()` function.

TLS 1.2 redefines the PRF, using an explicit hash function. The `br_tls12_sha256_prf()` and `br_tls12_sha384_prf()` functions apply that PRF with, respectively, SHA-256 and SHA-384. Most standard cipher suites rely on the SHA-256 based PRF, but some use SHA-384.

The PRF always uses as input three parameters: a "secret" (some bytes), a "label" (ASCII string), and a "seed" (again some bytes). An arbitrary output length can be produced. The "seed" is provided as an arbitrary number of binary chunks, that gets internally concatenated.

## Typedef Documentation

## ◆ br_tls_prf_impl

typedef void(* br_tls_prf_impl) (void *dst, size_t len, const void *secret, size_t secret_len, const char *label, size_t seed_num, const br_tls_prf_seed_chunk *seed)

brief A convenient type name for a PRF implementation.

Parameters

  dst | destination buffer.
  len | output length (in bytes).
  secret | secret value (key) for this computation.
  secret_len | length of "secret" (in bytes).
  label | PRF label (zero-terminated ASCII string).
  seed_num | number of seed chunks.
  seed | seed chnks for this computation (usually non-secret).

## Function Documentation

## ◆ br_tls10_prf()

void br_tls10_prf | ( | void * | dst,
|  | size_t | len,
|  | const void * | secret,
|  | size_t | secret_len,
|  | const char * | label,
|  | size_t | seed_num,
|  | const br_tls_prf_seed_chunk * | seed )

PRF implementation for TLS 1.0 and 1.1.

This PRF is the one specified by TLS 1.0 and 1.1. It internally uses MD5 and SHA-1.

Parameters

  dst | destination buffer.
  len | output length (in bytes).
  secret | secret value (key) for this computation.
  secret_len | length of "secret" (in bytes).
  label | PRF label (zero-terminated ASCII string).
  seed_num | number of seed chunks.
  seed | seed chnks for this computation (usually non-secret).

## ◆ br_tls12_sha256_prf()

void br_tls12_sha256_prf | ( | void * | dst,
|  | size_t | len,
|  | const void * | secret,
|  | size_t | secret_len,
|  | const char * | label,
|  | size_t | seed_num,
|  | const br_tls_prf_seed_chunk * | seed )

PRF implementation for TLS 1.2, with SHA-256.

This PRF is the one specified by TLS 1.2, when the underlying hash function is SHA-256.

Parameters

  dst | destination buffer.
  len | output length (in bytes).
  secret | secret value (key) for this computation.
  secret_len | length of "secret" (in bytes).
  label | PRF label (zero-terminated ASCII string).
  seed_num | number of seed chunks.
  seed | seed chnks for this computation (usually non-secret).

## ◆ br_tls12_sha384_prf()

void br_tls12_sha384_prf | ( | void * | dst,
|  | size_t | len,
|  | const void * | secret,
|  | size_t | secret_len,
|  | const char * | label,
|  | size_t | seed_num,
|  | const br_tls_prf_seed_chunk * | seed )

PRF implementation for TLS 1.2, with SHA-384.

This PRF is the one specified by TLS 1.2, when the underlying hash function is SHA-384.

Parameters

  dst | destination buffer.
  len | output length (in bytes).
  secret | secret value (key) for this computation.
  secret_len | length of "secret" (in bytes).
  label | PRF label (zero-terminated ASCII string).
  seed_num | number of seed chunks.
  seed | seed chnks for this computation (usually non-secret).