Create and verify digital signatures. More...

Public Types
enum class	Alg
	Signature algorithm. More...

enum class	Encoding
	Encoding for signature output. More...

enum	SigOptions : unsigned int
	Specialist options for signatures [BitFlags]. More...

enum class	VerifyOpts
	Specialist options for verifying a signature. More...

Static Public Member Functions
static std::string	AlgName (Sig::Alg alg)
	Get the algorithm name. More...

static std::string	GetHashNameFromSigAlg (Sig::Alg sigAlg)
	Get the hash algorithm used in the signature algorithm. More...

static std::string	SignData (const bvec_t &data, const std::string &keyFileOrString, const std::string &password="", Alg alg=Alg::Default, Encoding encoding=Encoding::Base64, SigOptions opts=SigOptions::None)
	Compute a signature value over data in a byte array. More...

static std::string	SignDigest (const bvec_t &digest, const std::string &keyFileOrString, const std::string &password="", Alg alg=Alg::Default, Encoding encoding=Encoding::Base64, SigOptions opts=SigOptions::None)
	Compute a signature value over a message digest value. More...

static std::string	SignFile (const std::string &dataFile, const std::string &keyFileOrString, const std::string &password="", Alg alg=Alg::Default, Encoding encoding=Encoding::Base64, SigOptions opts=SigOptions::None)
	Compute a signature value over binary data in a file. More...

static bool	VerifyData (const std::string &sigStr, const bvec_t &data, const std::string &certOrKey, Alg alg=Alg::Default, VerifyOpts opts=VerifyOpts::Default)
	Verify a signature value over data in a byte array. More...

static bool	VerifyDigest (const std::string &sigStr, const bvec_t &digest, const std::string &certOrKey, Alg alg=Alg::Default, VerifyOpts opts=VerifyOpts::Default)
	Verify a signature value over a message digest value of data. More...

static bool	VerifyFile (const std::string &sigStr, const std::string &dataFile, const std::string &certOrKey, Alg alg=Alg::Default, VerifyOpts opts=VerifyOpts::Default)
	Verify a signature value over data in a file. More...

Detailed Description

Create and verify digital signatures.

Member Enumeration Documentation

◆ Alg

enum dipki::Sig::Alg

strong

Signature algorithm.

Enumerator
Default	Use default signature algorithm [rsa-sha1/`sha1WithRSAEncryption`].
Rsa_Sha1	Use `sha1WithRSAEncryption` (rsa-sha1) signature algorithm [default - CAUTION]
Rsa_Sha224	Use `sha224WithRSAEncryption` (rsa-sha224) signature algorithm
Rsa_Sha256	Use `sha256WithRSAEncryption` (rsa-sha256) signature algorithm [minimum recommended].
Rsa_Sha384	Use `sha384WithRSAEncryption` (rsa-sha384) signature algorithm.
Rsa_Sha512	Use `sha512WithRSAEncryption` (rsa-sha512) signature algorithm.
Rsa_Md5	Use md5WithRSAEncryption (rsa-md5) signature algorithm [legacy, not recommended]
Rsa_Pss_Sha1	Use RSA-PSS signature algorithm with SHA-1.
Rsa_Pss_Sha224	Use RSA-PSS signature algorithm with SHA-224.
Rsa_Pss_Sha256	Use RSA-PSS signature algorithm with SHA-256.
Rsa_Pss_Sha384	Use RSA-PSS signature algorithm with SHA-384.
Rsa_Pss_Sha512	Use RSA-PSS signature algorithm with SHA-512.
Ecdsa_Sha1	Use `ecdsaWithSHA1` (ecdsa-sha1) signature algorithm
Ecdsa_Sha224	Use `ecdsaWithSHA224` (ecdsa-sha224) signature algorithm
Ecdsa_Sha256	Use `ecdsaWithSHA256` (ecdsa-sha256) signature algorithm
Ecdsa_Sha384	Use `ecdsaWithSHA384` (ecdsa-sha384) signature algorithm
Ecdsa_Sha512	Use `ecdsaWithSHA512` (ecdsa-sha512) signature algorithm
Ed25519	Use Ed25519 signature algorithm [RFC8032].
Ed448	Use Ed448 signature algorithm [RFC8032].

◆ Encoding

enum dipki::Sig::Encoding

strong

Encoding for signature output.

Enumerator
Base64	Base64 encoding (default)
Base64url	URL-safe base64 encoding as in section 5 of [RFC4648].
Base16	Base16 encoding (that is, hexadecimal)

◆ SigOptions

enum dipki::Sig::SigOptions : unsigned int

Specialist options for signatures [BitFlags].

Enumerator
None	Use default options for signature.
UseDeterministic	ECDSA only: Use the deterministic digital signature generation procedure of [RFC6979] for ECDSA signature [default=random k].
Asn1DERStructure	ECDSA only: Form ECDSA signature value as a DER-encoded ASN.1 structure [default=`r\|\|s`].
PssSaltLenHlen	RSA-PSS only: Set the salt length to hLen, the length of the output of the hash function [default].
PssSaltLenMax	RSA-PSS only: Set the salt length to the maximum possible (like OpenSSL).
PssSaltLen20	RSA-PSS only: Set the salt length to be exactly 20 bytes regardless of the hash algorithm.
PssSaltLenZero	RSA-PSS only: Set the salt length to be zero.
Mgf1Sha1	RSA-PSS only: Force the MGF hash function to be SHA-1 [default=same as signature hash algorithm].
Mgf1Sha1	RSA-PSS only: Force the MGF hash function to be SHA-1 [default=same as signature hash algorithm].

◆ VerifyOpts

enum dipki::Sig::VerifyOpts

strong

Specialist options for verifying a signature.

Enumerator
Default	Use default options.
Mgf1Sha1	RSA-PSS only: Force the MGF hash function to be SHA-1 [default=same as signature hash algorithm].

Member Function Documentation

◆ AlgName()

static std::string dipki::Sig::AlgName ( Sig::Alg alg )

static

Get the algorithm name.

Parameters

alg	Signature algorithm

Returns: Algorithm name as a string, e.g. "rsa-256".
cout << dipki::Sig::AlgName(dipki::Sig::Alg::Rsa_Sha256) << endl;

// rsa-sha256

dipki::Sig::Alg::Rsa_Sha256
@ Rsa_Sha256
Use sha256WithRSAEncryption (rsa-sha256) signature algorithm [minimum recommended].

dipki::Sig::AlgName
static std::string AlgName(Sig::Alg alg)
Get the algorithm name.

◆ GetHashNameFromSigAlg()

static std::string dipki::Sig::GetHashNameFromSigAlg ( Sig::Alg sigAlg )

static

Get the hash algorithm used in the signature algorithm.

Parameters

sigAlg Signature algorithm

Returns: Hash algorithm used in sigAlg as a string e.g. "sha256".
cout << dipki::Sig::GetHashNameFromSigAlg(dipki::Sig::Alg::Rsa_Sha256) << endl;

// sha256

dipki::Sig::GetHashNameFromSigAlg
static std::string GetHashNameFromSigAlg(Sig::Alg sigAlg)
Get the hash algorithm used in the signature algorithm.

Remarks: Use Hash::HashAlgFromString to get the Hash::Alg enumeration.

◆ SignData()

static std::string dipki::Sig::SignData	(	const bvec_t &	data,
		const std::string &	keyFileOrString,
		const std::string &	password = `""`,
		Alg	alg = `Alg::Default`,
		Encoding	encoding = `Encoding::Base64`,
		SigOptions	opts = `SigOptions::None`
	)

static

Compute a signature value over data in a byte array.

Parameters

data	Input data to be signed.
keyFileOrString	Name of private key file (or a string containing the key in PEM format, or an internal private key).
password	Password for the private key (if encrypted).
alg	Signature algorithm to be used.
encoding	Encoding for output [default=base64].
opts	Specialist options for RSA-PSS and ECDSA signatures.

Returns: The encoded signature value. By default, a continuous string of base64 characters suitable for the <SignatureValue> of an XML-DSIG document.

◆ SignDigest()

static std::string dipki::Sig::SignDigest	(	const bvec_t &	digest,
		const std::string &	keyFileOrString,
		const std::string &	password = `""`,
		Alg	alg = `Alg::Default`,
		Encoding	encoding = `Encoding::Base64`,
		SigOptions	opts = `SigOptions::None`
	)

static

Compute a signature value over a message digest value.

Parameters

digest	Digest value.
keyFileOrString	Name of private key file (or a string containing the key in PEM format, or an internal private key).
password	Password for the private key (if encrypted).
alg	Signature algorithm to be used.
encoding	Encoding for output [default=base64].
opts	Specialist options for RSA-PSS and ECDSA signatures.

Returns: The encoded signature value.

Remarks: The digest value must have a length equal to the hash length of the underlying hash function used in the signature algorithm. Cannot be used for Ed25519.

◆ SignFile()

static std::string dipki::Sig::SignFile	(	const std::string &	dataFile,
		const std::string &	keyFileOrString,
		const std::string &	password = `""`,
		Alg	alg = `Alg::Default`,
		Encoding	encoding = `Encoding::Base64`,
		SigOptions	opts = `SigOptions::None`
	)

static

Compute a signature value over binary data in a file.

Parameters

dataFile	Name of input file containing data to be signed.
keyFileOrString	Name of private key file (or a string containing the key in PEM format, or an internal private key).
password	Password for the private key (if encrypted).
alg	Signature algorithm to be used.
encoding	Encoding for output [default=base64].
opts	Specialist options for RSA-PSS and ECDSA signatures.

Returns: The encoded signature value.

Remarks: The digest value must have a length equal to the hash length of the underlying hash function used in the signature algorithm. Not applicable for Ed25519.

◆ VerifyData()

static bool dipki::Sig::VerifyData	(	const std::string &	sigStr,
		const bvec_t &	data,
		const std::string &	certOrKey,
		Alg	alg = `Alg::Default`,
		VerifyOpts	opts = `VerifyOpts::Default`
	)

static

Verify a signature value over data in a byte array.

Parameters

sigStr	Encoded signature value.
data	Input data to be verified.
certOrKey	The X.509 certificate or public key file name (or a string containing the certificate or key in PEM format or base64 representation, or an internal key string).
alg	Signature algorithm used to create signature.
opts	Specialist options for RSA-PSS only

Returns: true if the signature is valid, false if invalid.

Remarks: A signature value is considered valid if it can be decrypted by the public key in certOrKey and the digest value of the data matches the original digest of the data in the signature. Any supported encodings of the signature value are detected automatically.

Exceptions

std::runtime_error Exception with error code if parameters or formats are bad, or if file is missing.

◆ VerifyDigest()

static bool dipki::Sig::VerifyDigest	(	const std::string &	sigStr,
		const bvec_t &	digest,
		const std::string &	certOrKey,
		Alg	alg = `Alg::Default`,
		VerifyOpts	opts = `VerifyOpts::Default`
	)

static

Verify a signature value over a message digest value of data.

Parameters

sigStr	Encoded signature value.
digest	Digest value of the data to be verified.
certOrKey	The X.509 certificate or public key file name (or a string containing the certificate or key in PEM format or base64 representation, or an internal key string).
alg	Signature algorithm used to create signature.
opts	Specialist options for RSA-PSS only

Returns: true if the signature is valid, false if invalid.

Exceptions

std::runtime_error Exception with error code if parameters or formats are bad, or if file is missing.

◆ VerifyFile()

static bool dipki::Sig::VerifyFile	(	const std::string &	sigStr,
		const std::string &	dataFile,
		const std::string &	certOrKey,
		Alg	alg = `Alg::Default`,
		VerifyOpts	opts = `VerifyOpts::Default`
	)

static

Verify a signature value over data in a file.

Parameters

sigStr	Encoded signature value.
dataFile	Name of file containing data to be verified.
certOrKey	The X.509 certificate or public key file name (or a string containing the certificate or key in PEM format or base64 representation, or an internal key string).
alg	Signature algorithm used to create signature.
opts	Specialist options for RSA-PSS only

Returns: true if the signature is valid, false if invalid.

Exceptions

std::runtime_error Exception with error code if parameters or formats are bad, or if file is missing.

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Alg

◆ Encoding

◆ SigOptions

◆ VerifyOpts

Member Function Documentation

◆ AlgName()

◆ GetHashNameFromSigAlg()

◆ SignData()

◆ SignDigest()

◆ SignFile()

◆ VerifyData()

◆ VerifyDigest()

◆ VerifyFile()