A convenience class for PKCS11 based cryptographic operations. More...

#include <PKCS11Backend.h>

Classes
struct	Handle

Public Member Functions
	PKCS11Backend (const std::string &path)
	Construct a new PKCS11Backend object.

	~PKCS11Backend ()

std::vector< Handle >	findCertificates (const std::string &label)
	find all certificates with given label

std::vector< Handle >	findCertificates (const std::vector< uint8_t > &public_key)
	find all certificates for given public key

std::vector< Handle >	findSecretKeys (const std::string &label)
	find all secret keys with given label

result_t	useSecretKey (int slot, const std::vector< uint8_t > &pin, const std::vector< uint8_t > &id, const std::string &label)
	load secret key

result_t	usePrivateKey (int slot, const std::vector< uint8_t > &pin, const std::vector< uint8_t > &id, const std::string &label)
	loads private key

result_t	getCertificate (std::vector< uint8_t > &val, bool &rsa, int slot, const std::vector< uint8_t > &pin, const std::vector< uint8_t > &id, const std::string &label)
	get certificate value

result_t	getPublicKey (std::vector< uint8_t > &val, bool &rsa, int slot, const std::vector< uint8_t > &pin, const std::vector< uint8_t > &id, const std::string &label)
	get public key value

virtual result_t	connectToKey (int idx, bool priv)
	loads key for encryption/decryption

virtual result_t	usePSS (int idx)
	whether to use PSS RSA padding

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

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

virtual result_t	extractHKDF (std::vector< uint8_t > &kek, const std::vector< uint8_t > &salt, const std::vector< uint8_t > &pw_salt, int32_t kdf_iter, unsigned int idx) override
	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) override
	sign Sign message with given algorithm

Public Member Functions inherited from libcdoc::CryptoBackend
	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	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 int	test (libcdoc::Lock &lock)

Additional Inherited Members
Public Types inherited from libcdoc::CryptoBackend
enum	HashAlgorithm : uint32_t { SHA_224 , SHA_256 , SHA_384 , SHA_512 }

Static Public Attributes inherited from libcdoc::CryptoBackend
static constexpr int	INVALID_PARAMS = -201

static constexpr int	OPENSSL_ERROR = -202

static constexpr int	ECC_KEY_LEN = 32

Detailed Description

A convenience class for PKCS11 based cryptographic operations.

It has default implementations of all CryptoBackend methods. Instead the user has to implement connectToKey method. The latter should find the correct private or secret key for the lock and then call either usePrivateKey or useSecretKey to load the key.

Constructor & Destructor Documentation

◆ PKCS11Backend()

libcdoc::PKCS11Backend::PKCS11Backend ( const std::string & path )

Construct a new PKCS11Backend object.

Parameters

path	a path to PKCS11 library to use (usually .so or .dll depending on operating system)

◆ ~PKCS11Backend()

libcdoc::PKCS11Backend::~PKCS11Backend ( )

Member Function Documentation

◆ connectToKey()

virtual result_t libcdoc::PKCS11Backend::connectToKey	(	int	idx,
		bool	priv
	)

inlinevirtual

loads key for encryption/decryption

A method to load the correct private/secret key for given capsule or receiver. The subclass implementation should call either useSecretKey or usePrivateKey with proper pin, PKCS11 label and/or id to actually load the key for subsequent cryptographic operation.

Parameters

idx	lock or recipient index (0-based) in CDoc container
priv	whether to connect to private or secret key

Returns: error code or OK

References libcdoc::NOT_IMPLEMENTED.

◆ decryptRSA()

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

overridevirtual

decryptRSA

Parameters

dst	the destination container for decrypted data
data	encrypted data
oaep	use OAEP padding
idx	lock index (0-based) in container

Returns: error code or OK

Reimplemented from libcdoc::CryptoBackend.

◆ deriveECDH1()

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

overridevirtual

Derive shared secret.

Derive a shared secret from private key of given lock and public key 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 from libcdoc::CryptoBackend.

◆ extractHKDF()

virtual result_t libcdoc::PKCS11Backend::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
	)

overridevirtual

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 from libcdoc::CryptoBackend.

◆ findCertificates() [1/2]

std::vector< Handle > libcdoc::PKCS11Backend::findCertificates ( const std::string & label )

find all certificates with given label

A convenience method to fetch all certificates in all slots with given label. If the label is empty, returns all certificates.

Parameters

label a certificate label or empty string

Returns: a vector of handles

◆ findCertificates() [2/2]

std::vector< Handle > libcdoc::PKCS11Backend::findCertificates ( const std::vector< uint8_t > & public_key )

find all certificates for given public key

A convenience method to fetch all certificates in all slots with given public key.

Parameters

public_key public key (short form)

Returns: a list of handles

◆ findSecretKeys()

std::vector< Handle > libcdoc::PKCS11Backend::findSecretKeys ( const std::string & label )

find all secret keys with given label

A convenience method to fetch all secret keys in all slots with given label. If the label is empty, returns all secret keys.

Parameters

label a certificate label or empty string

Returns: a vector of handles

◆ getCertificate()

result_t libcdoc::PKCS11Backend::getCertificate	(	std::vector< uint8_t > &	val,
		bool &	rsa,
		int	slot,
		const std::vector< uint8_t > &	pin,
		const std::vector< uint8_t > &	id,
		const std::string &	label
	)

get certificate value

Get a certificate value given slot, label and id. Both key id and label have to match unless either one is empty.

Parameters

val	a destination container for value
rsa	will be set true is certificate uses RSA key
slot	the slot to use
pin	the pin code
id	certificate id or empty vector
label	certificate label or empty vector

Returns: error code or OK

◆ getPublicKey()

result_t libcdoc::PKCS11Backend::getPublicKey	(	std::vector< uint8_t > &	val,
		bool &	rsa,
		int	slot,
		const std::vector< uint8_t > &	pin,
		const std::vector< uint8_t > &	id,
		const std::string &	label
	)

get public key value

Get a public key value given slot, label and id. Both key id and label have to match unless either one is empty.

Parameters

val	a destination container for value
rsa	will be set true is public key uses RSA key
slot	the slot to use
pin	the pin code
id	public key id or empty vector
label	public key label or empty vector

Returns: error code or OK

◆ sign()

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

overridevirtual

sign Sign message with given algorithm

Parameters

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

Returns: error code or OK

Reimplemented from libcdoc::CryptoBackend.

◆ usePrivateKey()

result_t libcdoc::PKCS11Backend::usePrivateKey	(	int	slot,
		const std::vector< uint8_t > &	pin,
		const std::vector< uint8_t > &	id,
		const std::string &	label
	)

loads private key

Opens slot, logs in with pin and finds the correct private key. Both key id and label have to match unless either one is empty. If the key is found, it is loaded internally for subsequent cryptographic operations.

Parameters

slot	a PKCS11 slot to use
pin	a user pin
id	the key id
label	the key label

Returns: error code or OK

◆ usePSS()

virtual result_t libcdoc::PKCS11Backend::usePSS ( int idx )

inlinevirtual

whether to use PSS RSA padding

A subclass should overwrite this to inform the backend about the correct padding.

Parameters

idx	a lock idx

Returns: true if PSS padding is sued

◆ useSecretKey()

result_t libcdoc::PKCS11Backend::useSecretKey	(	int	slot,
		const std::vector< uint8_t > &	pin,
		const std::vector< uint8_t > &	id,
		const std::string &	label
	)

load secret key

Opens slot, logs in with pin and finds the correct secret key. Both key id and label have to match unless either one is empty. If the key is found, it is loaded internally for subsequent cryptographic operations.

Parameters

slot	a PKCS11 slot to use
pin	a user pin
id	the key id or empty vector
label	the key label or empty string

Returns: error code or OK

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

PKCS11Backend.h

Classes

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PKCS11Backend()

◆ ~PKCS11Backend()

Member Function Documentation

◆ connectToKey()

◆ decryptRSA()

◆ deriveECDH1()

◆ extractHKDF()

◆ findCertificates() [1/2]

◆ findCertificates() [2/2]

◆ findSecretKeys()

◆ getCertificate()

◆ getPublicKey()

◆ sign()

◆ usePrivateKey()

◆ usePSS()

◆ useSecretKey()