An authentication provider. More...

#include <CryptoBackend.h>

Inherited by libcdoc::PKCS11Backend, and libcdoc::WinBackend.

Public Types
enum	HashAlgorithm : uint32_t { SHA_224 , SHA_256 , SHA_384 , SHA_512 }

Public Member Functions
	CryptoBackend ()=default

virtual	~CryptoBackend () noexcept=default

	CryptoBackend (const CryptoBackend &)=delete

CryptoBackend &	operator= (const CryptoBackend &)=delete

	CDOC_DISABLE_MOVE (CryptoBackend)

virtual std::string	getLastErrorStr (result_t code) const

virtual result_t	random (std::vector< uint8_t > &dst, unsigned int size)
	Fill vector with random bytes.

virtual result_t	deriveECDH1 (std::vector< uint8_t > &dst, const std::vector< uint8_t > &public_key, unsigned int idx)
	Derive shared secret.

virtual result_t	decryptRSA (std::vector< uint8_t > &dst, const std::vector< uint8_t > &data, bool oaep, unsigned int idx)
	decrypt RSA ciphertext

virtual result_t	deriveConcatKDF (std::vector< uint8_t > &dst, const std::vector< uint8_t > &public_key, const std::string &digest, const std::vector< uint8_t > &algorithm_id, const std::vector< uint8_t > &party_uinfo, const std::vector< uint8_t > &party_vinfo, unsigned int idx)
	Derive key by ConcatKDF algorithm.

virtual result_t	deriveHMACExtract (std::vector< uint8_t > &dst, const std::vector< uint8_t > &public_key, const std::vector< uint8_t > &salt, unsigned int idx)
	Get CDoc2 KEK pre-master from ECC key.

virtual result_t	getSecret (std::vector< uint8_t > &dst, unsigned int idx)
	Get secret value (either password or symmetric key) for a lock.

virtual result_t	getKeyMaterial (std::vector< uint8_t > &dst, const std::vector< uint8_t > &pw_salt, int32_t kdf_iter, unsigned int idx)
	Get CDoc2 key material for HKDF expansion.

virtual result_t	extractHKDF (std::vector< uint8_t > &dst, const std::vector< uint8_t > &salt, const std::vector< uint8_t > &pw_salt, int32_t kdf_iter, unsigned int idx)
	Get CDoc2 KEK pre-master from symmetric key.

virtual result_t	sign (std::vector< uint8_t > &dst, HashAlgorithm algorithm, const std::vector< uint8_t > &digest, unsigned int idx)
	sign Sign message with given hash algorithm using the private key of given lock

virtual int	test (libcdoc::Lock &lock)

Static Public Attributes
static constexpr int	INVALID_PARAMS = -201

static constexpr int	OPENSSL_ERROR = -202

static constexpr int	ECC_KEY_LEN = 32

Detailed Description

An authentication provider.

Implements cryptographic methods that may need either user action (supplying password) or external communication (PKCS11). At minimum one should implement:

deriveECDH1 for ECC keys
decryptRSA for RSA keys
getSecret for symmetric keys.

ECC and symmetric keys have also frontend methods; implementing these allows the program to perform certain cryptographic procedures in secure environment and (in case of symmetric keys) avoid exposing secret keys/passwords to library code.

Member Enumeration Documentation

◆ HashAlgorithm

enum libcdoc::CryptoBackend::HashAlgorithm : uint32_t

Enumerator
SHA_224
SHA_256
SHA_384
SHA_512

Constructor & Destructor Documentation

◆ CryptoBackend() [1/2]

libcdoc::CryptoBackend::CryptoBackend ( )

default

◆ ~CryptoBackend()

virtual libcdoc::CryptoBackend::~CryptoBackend ( )

virtualdefaultnoexcept

◆ CryptoBackend() [2/2]

libcdoc::CryptoBackend::CryptoBackend ( const CryptoBackend & )

delete

Member Function Documentation

◆ CDOC_DISABLE_MOVE()

libcdoc::CryptoBackend::CDOC_DISABLE_MOVE ( CryptoBackend )

◆ decryptRSA()

virtual result_t libcdoc::CryptoBackend::decryptRSA	(	std::vector< uint8_t > &	dst,
		const std::vector< uint8_t > &	data,
		bool	oaep,
		unsigned int	idx
	)

inlinevirtual

decrypt RSA ciphertext

If oaep == false the implementations MUST apply the implicit-rejection countermeasure (RFC 8017 section 7.2.2 / OpenSSL 3.2's EVP_PKEY_CTX_set_rsa_implicit_rejection): on padding failure they MUST return OK with dst filled with deterministic synthetic plaintext derived from the private key, and otherwise the recovered plaintext, both indistinguishable to an attacker who does not know the private key. The downstream AES decrypt acts as the authentication step that distinguishes a real key from a synthetic one. The dst has to be pre-allocated to the expected plaintext length by caller.

Parameters

dst	the destination container for decrypted data (has to be pre-allocated if `oaep` == false)
data	RSA ciphertext (wrapped FMK)
oaep	use OAEP padding
idx	lock index (0-based) in container

Returns: error code or OK

Reimplemented in libcdoc::WinBackend, and libcdoc::PKCS11Backend.

References libcdoc::NOT_IMPLEMENTED.

◆ deriveConcatKDF()

virtual result_t libcdoc::CryptoBackend::deriveConcatKDF	(	std::vector< uint8_t > &	dst,
		const std::vector< uint8_t > &	public_key,
		const std::string &	digest,
		const std::vector< uint8_t > &	algorithm_id,
		const std::vector< uint8_t > &	party_uinfo,
		const std::vector< uint8_t > &	party_vinfo,
		unsigned int	idx
	)

virtual

Derive key by ConcatKDF algorithm.

The ConcatKDF key derivation algorithm is defined in Section 5.8.1 of NIST SP 800-56A. The default implementation calls deriveECDH1 and performs local concatKDF

Parameters

dst	the container for derived key
public_key	ECDH public Key used to derive shared secret
digest	Digest method to use for ConcatKDF algorithm
algorithm_id	OtherInfo info parameters to input
party_uinfo	OtherInfo info parameters to input
party_vinfo	OtherInfo info parameters to input
idx	lock index (0-based) in container

Returns: error code or OK

Reimplemented in libcdoc::WinBackend.

◆ deriveECDH1()

virtual result_t libcdoc::CryptoBackend::deriveECDH1	(	std::vector< uint8_t > &	dst,
		const std::vector< uint8_t > &	public_key,
		unsigned int	idx
	)

inlinevirtual

Derive shared secret.

Derive a shared secret using the private key of recipient and the public key of lock using ECDH1 algorithm.

Parameters

dst	the container for shared secret
public_key	ECDH public key used to derive shared secret
idx	lock index (0-based) in container

Returns: error code or OK

Reimplemented in libcdoc::PKCS11Backend.

References libcdoc::NOT_IMPLEMENTED.

◆ deriveHMACExtract()

virtual result_t libcdoc::CryptoBackend::deriveHMACExtract	(	std::vector< uint8_t > &	dst,
		const std::vector< uint8_t > &	public_key,
		const std::vector< uint8_t > &	salt,
		unsigned int	idx
	)

virtual

Get CDoc2 KEK pre-master from ECC key.

Calculates KEK (Key Encryption Key) pre-master from an ECC public key. The default implementation calls deriveECDH1 and performs local HMAC extract

Parameters

dst	the container for derived key
public_key	ECDH public Key used to derive shared secret
salt	salt for key derivation
idx	lock index (0-based) in container

Returns: error code or OK

Reimplemented in libcdoc::WinBackend.

◆ extractHKDF()

virtual result_t libcdoc::CryptoBackend::extractHKDF	(	std::vector< uint8_t > &	dst,
		const std::vector< uint8_t > &	salt,
		const std::vector< uint8_t > &	pw_salt,
		int32_t	kdf_iter,
		unsigned int	idx
	)

virtual

Get CDoc2 KEK pre-master from symmetric key.

Calculates KEK (Key Encryption Key) pre-master from a symmetric key (either password or key-based). The default implementation calls getKeyMaterial and performs local HKDF extract.

Parameters

dst	the destination container for KEK pre-master
salt	the salt value for HKDF extract
pw_salt	the salt value for PBKDF
kdf_iter	the number of KDF iterations. If kdf_iter is 0, the key is plain symmetric key instead of password.
idx	lock or recipient index (0-based) in container

Returns: error code or OK

Reimplemented in libcdoc::PKCS11Backend.

◆ getKeyMaterial()

virtual result_t libcdoc::CryptoBackend::getKeyMaterial	(	std::vector< uint8_t > &	dst,
		const std::vector< uint8_t > &	pw_salt,
		int32_t	kdf_iter,
		unsigned int	idx
	)

virtual

Get CDoc2 key material for HKDF expansion.

Fetches key material for a symmetric key (either password or key-based). The default implementation calls getSecret and performs PBKDF2_SHA256 if key is password-based.

Parameters

dst	the destination container for key material
pw_salt	the salt value for PBKDF
kdf_iter	kdf_iter the number of KDF iterations. If kdf_iter is 0, the key is plain symmetric key instead of password.
idx	lock or recipient index (0-based) in container

Returns: error code or OK

◆ getLastErrorStr()

virtual std::string libcdoc::CryptoBackend::getLastErrorStr ( result_t code ) const

virtual

◆ getSecret()

virtual result_t libcdoc::CryptoBackend::getSecret	(	std::vector< uint8_t > &	dst,
		unsigned int	idx
	)

inlinevirtual

Get secret value (either password or symmetric key) for a lock.

Parameters

dst	the destination container for secret
idx	lock or recipient index (0-based) in container

Returns: error code or OK

References libcdoc::NOT_IMPLEMENTED.

◆ operator=()

CryptoBackend & libcdoc::CryptoBackend::operator= ( const CryptoBackend & )

delete

◆ random()

virtual result_t libcdoc::CryptoBackend::random	(	std::vector< uint8_t > &	dst,
		unsigned int	size
	)

virtual

Fill vector with random bytes.

Trim vector to requested size and fill it with random bytes. The default implementation uses OpenSSL randomness generator.

Parameters

dst	the destination container for randomness
size	the requested amount of random data

Returns: error code or OK

◆ sign()

virtual result_t libcdoc::CryptoBackend::sign	(	std::vector< uint8_t > &	dst,
		HashAlgorithm	algorithm,
		const std::vector< uint8_t > &	digest,
		unsigned int	idx
	)

inlinevirtual

sign Sign message with given hash algorithm using the private key of given lock

Parameters

dst	the destination container for signed message
algorithm	hashing algorithm
digest	a message to sign
idx	lock index (0-based) in container

Returns: error code or OK

Reimplemented in libcdoc::WinBackend, and libcdoc::PKCS11Backend.

References libcdoc::NOT_IMPLEMENTED.

◆ test()

virtual int libcdoc::CryptoBackend::test ( libcdoc::Lock & lock )

inlinevirtual

References libcdoc::NOT_IMPLEMENTED.

Member Data Documentation

◆ ECC_KEY_LEN

constexpr int libcdoc::CryptoBackend::ECC_KEY_LEN = 32

staticconstexpr

◆ INVALID_PARAMS

constexpr int libcdoc::CryptoBackend::INVALID_PARAMS = -201

staticconstexpr

◆ OPENSSL_ERROR

constexpr int libcdoc::CryptoBackend::OPENSSL_ERROR = -202

staticconstexpr

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

CryptoBackend.h

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ HashAlgorithm

Constructor & Destructor Documentation

◆ CryptoBackend() [1/2]

◆ ~CryptoBackend()

◆ CryptoBackend() [2/2]

Member Function Documentation

◆ CDOC_DISABLE_MOVE()

◆ decryptRSA()

◆ deriveConcatKDF()

◆ deriveECDH1()

◆ deriveHMACExtract()

◆ extractHKDF()

◆ getKeyMaterial()

◆ getLastErrorStr()

◆ getSecret()

◆ operator=()

◆ random()

◆ sign()

◆ test()

Member Data Documentation

◆ ECC_KEY_LEN

◆ INVALID_PARAMS

◆ OPENSSL_ERROR