#include <tls_crypt_v2.hpp>

Collaboration diagram for openvpn::TLSCryptV2ClientKey:

Public Types
enum	{ WKC_MAX_SIZE = 1024 }

Public Member Functions
	OPENVPN_SIMPLE_EXCEPTION (tls_crypt_v2_client_key_parse_error)

	OPENVPN_SIMPLE_EXCEPTION (tls_crypt_v2_client_key_encode_error)

	OPENVPN_SIMPLE_EXCEPTION (tls_crypt_v2_client_key_bad_size)

	TLSCryptV2ClientKey ()=delete

	TLSCryptV2ClientKey (TLSCryptContext::Ptr context)

bool	defined () const

void	parse (const std::string &key_text)

void	extract_key (OpenVPNStaticKey &tls_key)

std::string	render () const

void	extract_wkc (BufferAllocated &wkc_out) const

void	generate (StrongRandomAPI &rng, const TLSCryptV2ServerKey &server_key, const std::string &metadata, const int metadata_type, const std::optional< std::uint32_t > key_id, SSLLib::Ctx libctx=nullptr)
	Mint a fresh client key `Kc` and the WKc that carries it to a server.

Static Public Member Functions
static BufferAllocated	wrap (TLSCryptContext &context, const TLSCryptV2ServerKey &server_key, const unsigned char *kc, const size_t kc_size, const std::string &metadata, const int metadata_type, const std::optional< std::uint32_t > key_id, SSLLib::Ctx libctx=nullptr)
	Wrap client key material and metadata into a WKc.

Private Attributes
BufferAllocated	key

BufferAllocated	wkc

const size_t	key_size

const size_t	tag_size

TLSCryptContext::Ptr	context_
	The digest/cipher pair generate() wraps with.

Detailed Description

Definition at line 128 of file tls_crypt_v2.hpp.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
WKC_MAX_SIZE

Definition at line 131 of file tls_crypt_v2.hpp.

Constructor & Destructor Documentation

◆ TLSCryptV2ClientKey() [1/2]

openvpn::TLSCryptV2ClientKey::TLSCryptV2ClientKey ( )

delete

◆ TLSCryptV2ClientKey() [2/2]

openvpn::TLSCryptV2ClientKey::TLSCryptV2ClientKey ( TLSCryptContext::Ptr context )

inline

Definition at line 142 of file tls_crypt_v2.hpp.

Member Function Documentation

◆ defined()

bool openvpn::TLSCryptV2ClientKey::defined ( ) const

inline

Definition at line 149 of file tls_crypt_v2.hpp.

◆ extract_key()

void openvpn::TLSCryptV2ClientKey::extract_key ( OpenVPNStaticKey & tls_key )

inline

Definition at line 168 of file tls_crypt_v2.hpp.

Here is the caller graph for this function:

◆ extract_wkc()

void openvpn::TLSCryptV2ClientKey::extract_wkc ( BufferAllocated & wkc_out ) const

inline

Definition at line 185 of file tls_crypt_v2.hpp.

Here is the caller graph for this function:

◆ generate()

void openvpn::TLSCryptV2ClientKey::generate	(	StrongRandomAPI &	rng,
		const TLSCryptV2ServerKey &	server_key,
		const std::string &	metadata,
		const int	metadata_type,
		const std::optional< std::uint32_t >	key_id,
		SSLLib::Ctx	libctx = `nullptr`
	)

inline

Mint a fresh client key Kc and the WKc that carries it to a server.

Replaces any key already held, so that render() emits a complete client key file which a server holding server_key can unwrap.

Parameters

rng	Strong random source for `Kc`.
server_key	Server key to wrap under.
metadata	Metadata to embed; authenticated, but not interpreted here. Empty for a WKc carrying none.
metadata_type	Type byte prefixed to a non-empty `metadata:` 0x00 for opaque user metadata (what PG's CSV records use), 0x01 for the timestamp stock tls-crypt-v2-genkey emits.
key_id	Server key ID (`K_id`) naming `server_key`, or `std::nullopt` for a server configured with a single key.
libctx	SSL library context for the wrapping instance.

Exceptions

tls_crypt_v2_client_key_bad_size if metadata pushes the WKc past WKC_MAX_SIZE.

Definition at line 210 of file tls_crypt_v2.hpp.

Here is the caller graph for this function:

◆ OPENVPN_SIMPLE_EXCEPTION() [1/3]

openvpn::TLSCryptV2ClientKey::OPENVPN_SIMPLE_EXCEPTION ( tls_crypt_v2_client_key_bad_size )

◆ OPENVPN_SIMPLE_EXCEPTION() [2/3]

openvpn::TLSCryptV2ClientKey::OPENVPN_SIMPLE_EXCEPTION ( tls_crypt_v2_client_key_encode_error )

◆ OPENVPN_SIMPLE_EXCEPTION() [3/3]

openvpn::TLSCryptV2ClientKey::OPENVPN_SIMPLE_EXCEPTION ( tls_crypt_v2_client_key_parse_error )

◆ parse()

void openvpn::TLSCryptV2ClientKey::parse ( const std::string & key_text )

inline

Definition at line 154 of file tls_crypt_v2.hpp.

Here is the caller graph for this function:

◆ render()

std::string openvpn::TLSCryptV2ClientKey::render ( ) const

inline

Definition at line 173 of file tls_crypt_v2.hpp.

Here is the caller graph for this function:

◆ wrap()

static BufferAllocated openvpn::TLSCryptV2ClientKey::wrap	(	TLSCryptContext &	context,
		const TLSCryptV2ServerKey &	server_key,
		const unsigned char *	kc,
		const size_t	kc_size,
		const std::string &	metadata,
		const int	metadata_type,
		const std::optional< std::uint32_t >	key_id,
		SSLLib::Ctx	libctx = `nullptr`
	)

inlinestatic

Wrap client key material and metadata into a WKc.

The inverse of ProtoContext's unwrap_tls_crypt_wkc(), and the only producer of the wire format in this tree:

len = len(WKc)                                (16-bit, network byte order)
T   = HMAC-SHA256(Ka, len || K_id || Kc || metadata)
IV  = 128 most significant bits of T
WKc = T || AES-256-CTR(Ke, IV, Kc || metadata) || K_id || len

Ka and Ke are the HMAC and cipher halves of server_key.

Separate from generate() for callers that hold Kc already: tests building deliberately malformed WKc's, or a tool rewrapping an existing client key under a second server key.

Parameters

context	tls-crypt context supplying the digest and cipher.
server_key	Server key to wrap under.
kc	Client key material to embed.
kc_size	Bytes of `kc` to embed. Anything but a test wants OpenVPNStaticKey::KEY_SIZE: a server rejects a WKc carrying less than a full key.
metadata	Metadata payload, or empty for a WKc carrying none.
metadata_type	Type byte prefixed to a non-empty `metadata`.
key_id	Server key ID (`K_id`), or `std::nullopt` to omit it.
libctx	SSL library context for the wrapping instance.

Returns: The WKc, ready to append to a client key file or a handshake packet.

Exceptions

tls_crypt_v2_client_key_bad_size if the WKc would exceed WKC_MAX_SIZE.

Definition at line 256 of file tls_crypt_v2.hpp.

Here is the caller graph for this function:

Member Data Documentation

◆ context_

TLSCryptContext::Ptr openvpn::TLSCryptV2ClientKey::context_

private

The digest/cipher pair generate() wraps with.

Definition at line 330 of file tls_crypt_v2.hpp.

◆ key

BufferAllocated openvpn::TLSCryptV2ClientKey::key

private

Definition at line 323 of file tls_crypt_v2.hpp.

◆ key_size

const size_t openvpn::TLSCryptV2ClientKey::key_size

private

Definition at line 326 of file tls_crypt_v2.hpp.

◆ tag_size

const size_t openvpn::TLSCryptV2ClientKey::tag_size

private

Definition at line 327 of file tls_crypt_v2.hpp.

◆ wkc

BufferAllocated openvpn::TLSCryptV2ClientKey::wkc

private

Definition at line 324 of file tls_crypt_v2.hpp.

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

openvpn/crypto/tls_crypt_v2.hpp

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

Constructor & Destructor Documentation

◆ TLSCryptV2ClientKey() [1/2]

◆ TLSCryptV2ClientKey() [2/2]

Member Function Documentation

◆ defined()

◆ extract_key()

◆ extract_wkc()

◆ generate()

◆ OPENVPN_SIMPLE_EXCEPTION() [1/3]

◆ OPENVPN_SIMPLE_EXCEPTION() [2/3]

◆ OPENVPN_SIMPLE_EXCEPTION() [3/3]

◆ parse()

◆ render()

◆ wrap()

Member Data Documentation

◆ context_

◆ key

◆ key_size

◆ tag_size

◆ wkc