Public Key Cryptography¶
Public key cryptography is a collection of techniques allowing for encryption, signatures, and key agreement.
Key Objects¶
Public and private keys are represented by classes Public_Key and
Private_Key. Both derive from Asymmetric_Key.
Currently there is an inheritance relationship between Private_Key and
Public_Key, so that a private key can also be used as the corresponding
public key. It is best to avoid relying on this, as this inheritance will be
removed in a future major release.
-
class Asymmetric_Key¶
-
std::string algo_name()¶
Return a short string identifying the algorithm of this key, eg “RSA” or “ML-DSA”.
-
size_t estimated_strength() const¶
Return an estimate of the strength of this key, in terms of brute force key search. For example if this function returns 128, then it is is estimated to be roughly as difficult to crack as AES-128.
-
OID object_identifier() const¶
Return an object identifier which can be used to identify this type of key.
-
bool supports_operation(PublicKeyOperation op) const¶
Check if this key could be used for the queried operation type.
-
std::string algo_name()¶
-
class Public_Key¶
-
size_t key_length() const = 0;¶
Return an integer value that most accurately captures for the security level of the key. For example for RSA this returns the length of the public modules, while for ECDSA keys it returns the size of the elliptic curve group.
-
bool check_key(RandomNumberGenerator &rng, bool strong) const = 0;¶
Check if the key seems to be valid. If strong is set to true then more expensive tests are performed.
-
AlgorithmIdentifier algorithm_identifier() const = 0;¶
Return an X.509 algorithm identifier that can be used to identify the key.
-
std::vector<uint8_t> public_key_bits() const = 0;¶
Returns a binary representation of the public key. Typically this is a BER encoded structure that includes metadata like the algorithm and parameter set used to generate the key.
Note that pre-standard post-quantum algorithms of the NIST competition (e.g. Kyber, Dilithium, FrodoKEM, etc) do not have a standardized BER encoding, yet. For the time being, the raw public key bits are returned for these algorithms. That might change as the standards evolve.
-
std::vector<uint8_t> raw_public_key_bits() const = 0;¶
Returns a binary representation of the public key’s canonical structure. Typically, this does not include any metadata like an algorithm identifier or parameter set. Note that some schemes (e.g. RSA) do not know such “raw” canonical structure and therefore throw Not_Implemented. For key agreement algorithms, this is the canonical public value of the scheme.
Decoding the resulting raw bytes typically requires knowledge of the algorithm and parameters used to generate the key.
-
std::vector<uint8_t> subject_public_key() const;¶
Return the X.509
SubjectPublicKeyInfoencoding of this key. See RFC 5280 for details.
-
std::string fingerprint_public(const std::string &alg = "SHA-256") const;¶
Return a hashed fingerprint of this public key.
-
size_t key_length() const = 0;¶
-
class Private_Key¶
-
std::unique_ptr<Public_Key> public_key() const¶
Return an object containing the public key corresponding to this private key.
Prefer this over the (deprecated) implicit conversion of a private key to a public key currently possible due to an inheritance relation.
-
secure_vector<uint8_t> private_key_info() const¶
Return the key encoded as a PKCS #8 PrivateKeyInfo structure. See RFC 5208 for details.
Further functions relating to encoding and encrypting PKCS #8 private are detailed in Serializing Private Keys Using PKCS #8.
-
secure_vector<uint8_t> private_key_bits() const¶
Return the serialization of the private key, corresponding to the PrivateKey field of a PKCS #8 PrivateKeyInfo structure. See RFC 5208 for details.
-
bool stateful_operation() const;¶
Returns true if this keys operation is stateful, that is if updating the key is required after each private operation. Currently the only stateful schemes included are XMSS and LMS.
-
std::optional<uint64_t> remaining_operations() const¶
If this algorithm is stateful, returns the number of private operations remaining before this key is exhausted. Returns nullopt if the key is not stateful.
-
std::unique_ptr<Public_Key> public_key() const¶
Public Key Algorithms¶
Botan includes a number of public key algorithms, some of which are in common use, others only used in specialized or niche applications.
RSA¶
Based on the difficulty of factoring. Usable for encryption, signatures, and key encapsulation.
ECDSA¶
Fast signature scheme based on elliptic curves.
ECDH, DH, X25519 and X448¶
Key agreement schemes. DH uses arithmetic over finite fields and is slower and with larger keys. ECDH, X25519 and X448 use elliptic curves instead.
ML-DSA (FIPS 204)¶
Post-quantum secure signature scheme based on (structured) lattices. This algorithm is standardized in FIPS 204.
Private keys are encoded as the ML-DSA-PrivateKey structure of RFC 9881
in PKCS #8 containers. All three CHOICE alternatives of that structure are
supported when loading a key: the 32-byte private random seed (xi), the
expanded key specified in FIPS 204, or both. For backwards compatibility the
raw seed and the raw expanded key without ASN.1 wrapping are accepted as well
when loading a key. A loaded key retains the format it was loaded from and is
serialized in that format again; newly generated keys are serialized in the
seed format. Keys that contain the seed can be exported in any of the
formats using the common Private Key Formats of ML-KEM and ML-DSA interface, keys loaded
from the expanded key only cannot be exported as seed. Note that Botan versions
prior to 3.14 only accepted the raw seed as private key encoding; see
Private Key Formats of ML-KEM and ML-DSA for the consequences.
Support for ML-DSA is implemented in the module ml_dsa
Additionally, support for the pre-standardized version “Dilithium” is retained for the time being. The implemented specification is commonly referred to as version 3.1 of the CRYSTALS-Dilithium submission to NIST’s third round of the PQC competition. This is not compatible to the “Initial Public Draft” version of FIPS 204 for which Botan does not offer an implementation.
Currently two flavors of Dilithium are implemented in separate Botan modules:
dilithium, that uses Keccak (SHAKE), and that saw some public usage by early adopters.
dilithium_aes, that uses AES instead of Keccak-based primitives. This mode is deprecated and will be removed in a future release.
ML-KEM (FIPS 203)¶
Post-quantum key encapsulation scheme based on (structured) lattices. This algorithm is standardized in FIPS 203.
Private keys are encoded as the ML-KEM-PrivateKey structure of RFC 9935
in PKCS #8 containers. All three CHOICE alternatives of that structure are
supported when loading a key: the 64-byte private random seed (d || z), the
expanded decapsulation key specified in FIPS 203, or both. For backwards
compatibility the raw seed and the raw expanded key without ASN.1 wrapping are
accepted as well when loading a key. Loading an expanded key performs the hash
check of FIPS 203 and a pairwise consistency check; a key in the both format
is rejected if the expanded key is not the expansion of the seed. A loaded key
retains the format it was loaded from and is serialized in that format again;
newly generated keys are serialized in the seed format. Keys that contain
the seed can be exported in any of the formats using the common
Private Key Formats of ML-KEM and ML-DSA interface, keys loaded from the expanded key only
cannot be exported as seed. Note that Botan versions prior to 3.14 wrote the raw
seed or the raw expanded key into the PKCS #8 container and accept only those;
see Private Key Formats of ML-KEM and ML-DSA for the consequences.
Support for ML-KEM is implemented in the module ml_kem.
Additionally, support for the pre-standardized version “Kyber” is retained for the time being. The implemented specification is commonly referred to as version 3.01 of the CRYSTALS-Kyber submission to NIST’s third round of the PQC competition. This is not compatible to the “Initial Public Draft” version of FIPS 203 for which Botan does not offer an implementation.
Currently two flavors of Kyber are implemented in separate Botan modules:
kyber, that uses Keccak (SHAKE and SHA-3), and that saw some public usage by early adopters.
kyber_90s, that uses AES/SHA-2 instead of Keccak-based primitives. This mode is deprecated and will be removed in a future release.
Private Key Formats of ML-KEM and ML-DSA¶
Added in version 3.14.0.
The private keys of the module-lattice schemes ML-KEM and ML-DSA (and their
pre-standard variants Kyber and Dilithium) can be represented by their private
seed, by the expanded key of FIPS 203/204, or by both. Their key
classes ML_KEM_PrivateKey and ML_DSA_PrivateKey implement the common
interface Module_Lattice_PrivateKey declared in botan/module_lattice_keys.h,
which allows to query the format of a key and to encode it in a specific format.
Given a generic Private_Key, the interface is obtained with a
dynamic_cast<const Module_Lattice_PrivateKey*>.
-
enum class MlPrivateKeyFormat¶
-
enumerator Seed¶
Only the private random seed (64 bytes
d || zfor ML-KEM, 32 bytesxifor ML-DSA). This is the default for newly generated ML-KEM and ML-DSA keys. Not available for Kyber and Dilithium round 3 keys.
-
enumerator Expanded¶
The expanded private key as specified in FIPS 203 or FIPS 204.
-
enumerator Seed¶
-
class Module_Lattice_PrivateKey : public virtual Private_Key¶
-
MlPrivateKeyFormat private_key_format() const¶
The format this key was loaded from or, for a freshly generated key, the default format of the scheme (
Seedfor ML-KEM and ML-DSA,Expandedfor the pre-standard Kyber and Dilithium variants). This is the format used byprivate_key_bits(),private_key_info()andraw_private_key_bits().
-
secure_vector<uint8_t> formatted_raw_private_key_bits(MlPrivateKeyFormat format) const¶
The raw private key material in the given format without any ASN.1 wrapping, i.e. the bare seed or the expanded key. Throws
Encoding_Errorif the key cannot be encoded in the requested format. This is the case forBoth, which has no raw encoding, forSeedif the key was loaded from an expanded key, and for anything butExpandedon Kyber and Dilithium round 3 keys.
-
secure_vector<uint8_t> formatted_private_key_bits(MlPrivateKeyFormat format) const¶
The private key encoded in the given format as it appears in the
privateKeyfield of a PKCS #8PrivateKeyInfostructure. For ML-KEM this is theML-KEM-PrivateKeyencoding of RFC 9935, for ML-DSA theML-DSA-PrivateKeyencoding of RFC 9881. The pre-standard Kyber and Dilithium variants return the raw expanded key. ThrowsEncoding_Errorif the key cannot be encoded in the requested format.
-
secure_vector<uint8_t> private_key_bits() const¶
Equivalent to
formatted_private_key_bits(private_key_format()).
-
secure_vector<uint8_t> raw_private_key_bits() const¶
Equivalent to
formatted_raw_private_key_bits(private_key_format()), except that keys in the formatBothreturn the seed.
-
MlPrivateKeyFormat private_key_format() const¶
Newly generated ML-KEM and ML-DSA keys use the Seed format, storing only
the seed from which the key pair is expanded. The Expanded and Both
formats can be requested explicitly via formatted_private_key_bits().
Note the consequences for interoperability with earlier versions of Botan:
versions prior to 3.14 accept only the raw seed
(ML-DSA) or the raw seed or raw expanded key (ML-KEM) as content of the PKCS #8
privateKey field and cannot read any of the RFC 9881/9935 structures.
Botan 3.14 now instead produces PKCS #8 containers compliant to the respective RFC.
To transfer an RFC-compliant key to an earlier Botan version, export the raw key material with
raw_private_key_bits() or formatted_raw_private_key_bits() and load it
with the algorithm specific constructor (or botan_privkey_load_ml_kem
/ botan_privkey_load_ml_dsa in the FFI) in pre-3.14 Botan. Also note that
Private_Key::fingerprint_private() covers the encoded private key and thus
depends on the key’s format: a freshly generated key and the same key reloaded
from an expanded-only encoding have different fingerprints.
The method ML_KEM_PrivateKey::private_key_bits_with_format() is deprecated
in favor of formatted_raw_private_key_bits().
Ed25519 and Ed448¶
Signature schemes based on a specific elliptic curve.
XMSS¶
A post-quantum secure signature scheme whose security is based (only) on the security of a hash function. Unfortunately XMSS is stateful, meaning the private key changes with each signature, and only a certain pre-specified number of signatures can be created. If the same state is ever used to generate two signatures, then the whole scheme becomes insecure, and signatures can be forged.
Warning
Maintaining consistent state without replays is extremely difficult, especially when multiple machines are involved. Even a single error will compromise the entire signature scheme. XMSS should only be used in an environment carefully designed to maintain consistent state. Prefer the stateless SLH-DSA in new designs.
HSS-LMS¶
A post-quantum secure hash-based signature scheme similar to XMSS. Contains support for multitrees. It is stateful, meaning the private key changes after each signature. If the same state is ever used to generate two signatures, then the whole scheme becomes insecure, and signatures can be forged.
Warning
Maintaining consistent state without replays is extremely difficult, especially when multiple machines are involved. Even a single error will compromise the entire signature scheme. HSS-LMS should only be used in an environment carefully designed to maintain consistent state. Prefer the stateless SLH-DSA in new designs.
SLH-DSA (FIPS 205)¶
The Stateless Hash-Based Digital Signature Standard (SLH-DSA) is the FIPS 205 post-quantum secure signature scheme whose security is solely based on the security of a hash function. Unlike XMSS, it is a stateless signature scheme, meaning that the private key does not change with each signature. It has high security but very long signatures and high runtime.
Support for SLH-DSA is implemented in the modules slh_dsa_sha2 and slh_dsa_shake.
Additionally, support for the pre-standardized version “SPHINCS+” is retained for the time being. The implemented specification is commonly referred to as version 3.1 of the SPHINCS+ submission to NIST’s third round of the PQC competition. This is not compatible with the “Initial Public Draft” version of FIPS 205 for which Botan does not offer an implementation. Also, Botan does not support the Haraka hash function.
Currently, two flavors of SPHINCS+ are implemented in separate Botan modules:
sphincsplus_shake, that uses Keccak (SHAKE) hash functions
sphincsplus_sha2, that uses SHA-256
FrodoKEM¶
A post-quantum secure key encapsulation scheme based on (unstructured) lattices.
McEliece¶
Deprecated since version 3.0.0.
Post-quantum secure key encapsulation scheme based on the hardness of certain decoding problems. Deprecated; use Classic McEliece
Classic McEliece¶
Post-quantum secure, code-based key encapsulation scheme.
Warning
Recent research suggests that the security of Classic McEliece may be significantly lower than what was previously thought. The best known attacks are still very far from practical, but future advances may further erode the security. As of Sep 2026, Germany’s BSI recommends that Classic McEliece “should currently no longer be used in new developments or when planning new cryptographic applications” and that Classic McEliece be used only in a hybrid scheme, paired with either a classical EC algorithm or a lattice-based scheme such as ML-KEM.
ElGamal¶
Encryption scheme based on the discrete logarithm problem. Generally unused except in PGP.
DSA¶
Deprecated since version 3.7.0.
Finite field based signature scheme. A NIST standard but now quite obsolete.
ECGDSA, ECKCDSA, SM2, GOST-34.10¶
A set of signature schemes based on elliptic curves. All are national standards in their respective countries (Germany, South Korea, China, and Russia, resp), and are completely obscure and unused outside of that context.
GOST-34.10 support is deprecated.
Creating New Private Keys¶
Creating a new private key requires two things: a source of random numbers (see Random Number Generators) and potentially some algorithm specific parameters.
Generic Method¶
There is a generic method which can create keys of any algorithm type, defined
in pk_algs.h
-
std::unique_ptr<Private_Key> create_private_key(std::string_view algo, RandomNumberGenerator &rng, std::string_view params)¶
Examples of algorithm/parameter pairs that can be provided here:
“RSA” / “3072”
“ECDSA” / “secp256r1”
“Ed5519” / “”
“ML-KEM” / “ML-KEM-768”
“DH” / “modp/ietf/2048”
If params is left empty then a suitable algorithm-specific default will be chosen. This default may change from release to release, but generally tries to reflect a conservative setting.
Creating A New RSA Private Key¶
-
RSA_PrivateKey::RSA_PrivateKey(RandomNumberGenerator &rng, size_t bits)¶
A constructor that creates a new random RSA private key with a modulus of length bits.
RSA key generation is relatively slow, and can take an unpredictable amount of time. Generating a 2048 bit RSA key might take 5 to 10 seconds on a slow machine like a Raspberry Pi 2. Even on a fast desktop it might take up to half a second. In a GUI blocking for that long can be a problem. The usual approach is to perform key generation in a new thread, with a animated modal UI element so the user knows the application is still alive. If you wish to provide a progress estimate things get a bit complicated but some library users documented their approach in a blog post.
Creating A New EC Private Key¶
For a few schemes, the curve and signature scheme come as a package, and there are no extra parameters:
-
Ed25519_PrivateKey::Ed25519_PrivateKey(RandomNumberGenerator &rng)¶
Generate a new Ed25519 private key
-
Ed448_PrivateKey::Ed448_PrivateKey(RandomNumberGenerator &rng)¶
Generate a new Ed448 private key
-
X25519_PrivateKey::X25519_PrivateKey(RandomNumberGenerator &rng)¶
Generate a new X25519 private key
-
X448_PrivateKey::X448_PrivateKey(RandomNumberGenerator &rng)¶
Generate a new X448 private key
Others require additionally specifying which curve to use. First create a
relevant EC_Group using for example EC_Group::from_name
or EC_Group::from_OID. Then pass it to the private key
constructor. If the choice of group is not otherwise mandated by your
application, use “secp256r1” (aka P-256) or “secp384r1” (aka P-384) as they are
fastest, widely implemented, and considered secure.
-
ECDH_PrivateKey::ECDH_PrivateKey(RandomNumberGenerator &rng, const EC_Group &group)¶
Generate a new ECDH private key
-
ECDSA_PrivateKey::ECDSA_PrivateKey(RandomNumberGenerator &rng, const EC_Group &group)¶
Generate a new ECDSA private key
-
ECKCDSA_PrivateKey::ECKCDSA_PrivateKey(RandomNumberGenerator &rng, const EC_Group &group)¶
Generate a new ECKCDSA private key
-
ECGDSA_PrivateKey::ECGDSA_PrivateKey(RandomNumberGenerator &rng, const EC_Group &group)¶
Generate a new ECGDSA private key
-
GOST_3410_PrivateKey::GOST_3410_PrivateKey(RandomNumberGenerator &rng, const EC_Group &group)¶
Generate a new GOST-34.10 private key
-
SM2_PrivateKey::SM2_PrivateKey(RandomNumberGenerator &rng, const EC_Group &group)¶
Generate a new SM2 private key
Creating A New Finite Field DL Private Key¶
Instead of elliptic curves, some older algorithms are based on the security of discrete logarithms in the group of integers modulo a prime. For security, these require much larger keys than elliptic curve schemes, and are typically much slower.
Warning
Avoid such algorithms in new code
-
DH_PrivateKey::DH_PrivateKey(RandomNumberGenerator &rng, const DL_Group &group)¶
Create a new Diffie-Hellman private key. In most protocols that still support finite field DH, it is used with a set of pre-created and trusted groups. These were specified in RFC 3526 and are usually called the IETF MODP groups.
The MODP groups are built into the library and can be accessed by name for example
DL_Group::from_name("modp/ietf/3072"), where 3072 refers to the number of bits in the prime modulus.
-
DSA_PrivateKey::DSA_PrivateKey(RandomNumberGenerator &rng, const DL_Group &group)¶
Create a new DSA private key. DSA requires groups of a special form. The best way to create such a group is to create a new
DL_Groupat random for each key, using the “DSA kosherizer” algorithm. See DL_Group for more information.
-
ElGamal_PrivateKey::ElGamal_PrivateKey(RandomNumberGenerator &rng, const DL_Group &group)¶
Serializing Private Keys Using PKCS #8¶
The standard format for serializing a private key is PKCS #8, the operations
for which are defined in pkcs8.h. It supports both unencrypted and
encrypted storage.
-
secure_vector<uint8_t> PKCS8::BER_encode(const Private_Key &key, RandomNumberGenerator &rng, const std::string &password, const std::string &pbe_algo = "")¶
Takes any private key object, serializes it, encrypts it using password, and returns a binary structure representing the private key.
The final (optional) argument, pbe_algo, specifies a particular password based encryption (or PBE) algorithm. If you don’t specify a PBE, a sensible default will be used.
The currently supported PBE is PBES2 from PKCS5. Format is as follows:
PBE-PKCS5v20(CIPHER,PBKDF)orPBES2(CIPHER,PBKDF).Cipher can be any block cipher using CBC or GCM modes, for example “AES-128/CBC” or “Camellia-256/GCM”. For best interop with other systems, use AES in CBC mode. The PBKDF can be either the name of a hash function (in which case PBKDF2 is used with that hash) or “Scrypt”, which causes the scrypt memory hard password hashing function to be used. Scrypt is supported since version 2.7.0.
Use PBE-PKCS5v20(AES-256/CBC,SHA-256) if you want to ensure the keys can be imported by different software packages. Use PBE-PKCS5v20(AES-256/GCM,Scrypt) for best security assuming you do not care about interop.
For ciphers you can use anything which has an OID defined for CBC, GCM or SIV modes. Currently this includes AES, Camellia, Serpent, Twofish, and SM4. Most other libraries only support CBC mode for private key encryption. GCM has been supported in PBES2 since 2.0. SIV has been supported since 2.8.
-
std::string PKCS8::PEM_encode(const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo = "")¶
This formats the key in the same manner as
BER_encode, but additionally encodes it into a text format with identifying headers. Using PEM encoding is highly recommended for many reasons, including compatibility with other software, for transmission over 8-bit unclean channels, because it can be identified by a human without special tools, and because it sometimes allows more sane behavior of tools that process the data.
Unencrypted serialization is also supported.
Warning
In most situations, using unencrypted private key storage is a bad idea, because anyone can come along and grab the private key without having to know any passwords or other secrets. Unless you have very particular security requirements, always use the versions that encrypt the key based on a passphrase, described above.
-
secure_vector<uint8_t> PKCS8::BER_encode(const Private_Key &key)¶
Serializes the private key and returns the result.
-
std::string PKCS8::PEM_encode(const Private_Key &key)¶
Serializes the private key, base64 encodes it, and returns the result.
Last but not least, there are some functions that will load (and decrypt, if necessary) a PKCS #8 private key:
-
std::unique_ptr<Private_Key> load_key(DataSource &source, std::function<std::string()> get_passphrase)¶
-
std::unique_ptr<Private_Key> load_key(DataSource &source, const std::string &pass)¶
-
std::unique_ptr<Private_Key> load_key(DataSource &source)¶
These functions will return an object allocated key object based on the data
from whatever source it is using (assuming, of course, the source is in fact
storing a representation of a private key, and the decryption was
successful). The encoding used (PEM or BER) need not be specified; the format
will be detected automatically. The DataSource is usually a
DataSource_Stream to read from a file or DataSource_Memory for an
in-memory buffer.
The versions taking a std::string attempt to decrypt using the password
given (if the key is encrypted; if it is not, the passphase value will be
ignored). If the passphrase does not decrypt the key, an exception will be
thrown.
Serializing Public Keys¶
To import and export public keys, use:
-
std::vector<uint8_t> X509::BER_encode(const Public_Key &key)¶
-
std::string X509::PEM_encode(const Public_Key &key)¶
-
std::unique_ptr<Public_Key> X509::load_key(DataSource &in)¶
-
std::unique_ptr<Public_Key> X509::load_key(const secure_vector<uint8_t> &buffer)¶
-
std::unique_ptr<Public_Key> X509::load_key(const std::string &filename)¶
These functions operate in the same way as the ones described in Serializing Private Keys Using PKCS #8, except that no encryption option is available.
Note
In versions prior to 3.0, these functions returned a raw pointer instead of a
unique_ptr.
DL_Group¶
-
class DL_Group¶
Represents parameters for finite field discrete logarithm algorithms
-
static DL_Group DL_Group::from_name(std::string_view name)¶
The name here is a (Botan specific) identifier which maps to one of the standard discrete logarithm groups.
For the groups from RFC 5208 (often called the MODP groups, the IETF groups, or the IPsec groups) use “modp/ietf/N” where N can be any of 1024, 1536, 2048, 3072, 4096, 6144, or 8192. This group type is used for Diffie-Hellman and ElGamal algorithms, but cannot be used with DSA.
For the groups from RFC 7919 (often called the TLS FFDHE groups) use “ffdhe/ietf/N” where N is any of 2048, 3072, 4096, 6144, or 8192. These groups are typically only used in TLS, but can be used with Diffie-Hellman more generally. They cannot be used with DSA.
For the groups from RFC 5054 (the SRP6 groups) use “modp/srp/N” where N can be any of 1024, 1536, 2048, 3072, 4096, 6144, or 8192. These groups should only be used with SRP6.
Finally a small number of pre-created groups usable for DSA are available. These are “dsa/jce/1024”, “dsa/botan/2048”, and “dsa/botan/3072”. Support for these groups is deprecated and they will be removed in a future major release. Should DSA be required, create a new random group for each key.
You can generate a new random group using
-
DL_Group::DL_Group(RandomNumberGenerator &rng, PrimeType type, size_t pbits, size_t qbits = 0)¶
The type can be
Strong: A group where (p-1)/2 is also prime. Best for Diffie-Hellman, but very slow to generate.Prime_Subgroup: A group where (p-1) is divided by a large prime q, of sizeqbits. Faster to generate thanStrong, suitable for Diffie-Hellman.DSA_Kosherizer: Generate a group suitable for DSA using the algorithm specified in FIPS 186-3.
If qbits is set to zero then a suitable value is chosen relative to the value of pbits and the type of group being created.
You can serialize a DL_Group using
or
where format is any of
ANSI_X9_42(orDH_PARAMETERS) for modp groupsANSI_X9_57(orDSA_PARAMETERS) for DSA-style groupsPKCS_3is an older format for modp groups; it should only be used for backwards compatibility.
You can reload a serialized group from BER or PEM formats using
Code Example: DL_Group¶
The example below creates a new 2048 bit DL_Group, prints the generated
parameters and ANSI_X9_42 encodes the created group for further usage with DH.
#include <botan/auto_rng.h>
#include <botan/dl_group.h>
#include <botan/rng.h>
#include <iostream>
int main() {
Botan::AutoSeeded_RNG rng;
auto group = std::make_unique<Botan::DL_Group>(rng, Botan::DL_Group::Strong, 2048);
std::cout << "P = " << group->get_p().to_hex_string() << "\n"
<< "Q = " << group->get_q().to_hex_string() << "\n"
<< "G = " << group->get_g().to_hex_string() << "\n";
std::cout << "\nPEM:\n" << group->PEM_encode(Botan::DL_Group_Format::ANSI_X9_42) << "\n";
return 0;
}
Key Checking¶
Most public key algorithms have limitations or restrictions on their parameters. For example RSA requires an odd exponent, and algorithms based on the discrete logarithm problem need a generator > 1.
Each public key type has a function
-
bool Asymmetric_Key::check_key(RandomNumberGenerator &rng, bool strong)¶
This function performs a number of algorithm-specific tests that the key seems to be mathematically valid and consistent, and returns true if all of the tests pass.
It does not have anything to do with the validity of the key for any particular use, nor does it have anything to do with certificates that link a key (which, after all, is just some numbers) with a user or other entity. If strong is
true, then it does “strong” checking, which includes expensive operations like primality checking.
As key checks are not automatically performed they must be called manually after loading keys from untrusted sources. If a key from an untrusted source is not checked, the implementation might be vulnerable to algorithm specific attacks.
The following example loads the Subject Public Key from the x509
certificate cert.pem and checks the loaded key. If the key check
fails a respective error is thrown.
#include <botan/auto_rng.h>
#include <botan/pk_keys.h>
#include <botan/rng.h>
#include <botan/x509cert.h>
#include <iostream>
int main() {
const Botan::X509_Certificate cert("cert.pem");
Botan::AutoSeeded_RNG rng;
auto key = cert.subject_public_key();
if(!key->check_key(rng, false)) {
std::cerr << "Loaded key is invalid";
return 1;
}
return 0;
}
Public Key Encryption/Decryption¶
Safe public key encryption requires the use of a padding scheme which hides the underlying mathematical properties of the algorithm. Additionally, they will add randomness, so encrypting the same plaintext twice produces two different ciphertexts.
The padding scheme and its parameters are specified using a
PK_Encryption_Options object.
Encryption Options¶
Added in version 3.14.0.
-
class PK_Encryption_Options¶
Describes how a message is to be encrypted or decrypted. As with
PK_Signature_Options, the object is built up in a builder style; eachwith_xxxfunction returns a new options object with that option added:auto opts = Botan::PK_Encryption_Options() .with_padding("OAEP") .with_hash("SHA-256"); Botan::PK_Encryptor_EME enc(pub_key, rng, opts); Botan::PK_Decryptor_EME dec(priv_key, rng, opts);
Every option that is set must be understood and acted upon by the scheme in use; if it is not (for example a context with
PKCS1v15padding, or any padding scheme with SM2) then constructing thePK_Encryptor_EMEorPK_Decryptor_EMEthrows an exception naming the offending option(s). An option is never silently ignored. Each option can be set at most once; setting one a second time throwsInvalid_State.The encryptor and decryptor must be configured identically, since every option affects the ciphertext format.
-
PK_Encryption_Options()¶
Creates an empty set of options. This is sufficient only for SM2; RSA and ElGamal require a padding scheme.
-
PK_Encryption_Options with_padding(std::string_view padding)¶
Specify the padding scheme. RSA and ElGamal require this; the available schemes are
OAEP,PKCS1v15andRaw, described in Available encryption padding schemes. Encrypting without padding is dangerous, so there is no default. SM2 does not use padding and rejects this option.An empty string is ignored.
-
PK_Encryption_Options with_hash(std::string_view hash)¶
Specify the hash function.
OAEPrequires this; the hash is used for the label and, unlessPK_Encryption_Options::with_mgf1_hashis also given, for the mask generation function. For SM2 it selects the hash used within the scheme, and defaults to SM3 if not given.PKCS1v15andRawpadding do not use a hash and reject this option.An empty string is ignored.
-
PK_Encryption_Options with_mgf1_hash(std::string_view hash)¶
Use a different hash function for OAEP’s MGF1 than for the label. This is rarely needed, but some protocols (and some implementations, by default) use for example SHA-256 for OAEP with SHA-1 for MGF1. Only
OAEPsupports this option.An empty string is ignored.
-
PK_Encryption_Options with_context(std::span<const uint8_t> context)¶
-
PK_Encryption_Options with_context(std::string_view context)¶
Specify a context which is bound into the ciphertext. Currently this is only supported by
OAEP, where it is the label (Lin RFC 8017). The label defaults to the empty string. A ciphertext created with one label will not decrypt with another.
-
PK_Encryption_Options with_provider(std::string_view provider)¶
Request a specific implementation. This is rarely needed; the main use is with keys held in hardware (providers
pkcs11,tpm2), which accept only their own provider name.The hardware providers support
OAEPandPKCS1v15. PKCS#11 also supportsRaw. The TPM2 provider does not currently support an OAEP label, or an MGF1 hash differing from the OAEP hash.
-
std::string to_string() const¶
Formats the options as a string, for debugging and error messages. The format is not fixed.
-
PK_Encryption_Options()¶
Encryption Options Accepted by Each Scheme¶
RSA and ElGamal: require a padding scheme. With
OAEPa hash is also required, and an MGF1 hash and a context (the label) are accepted.PKCS1v15andRawtake no further options.SM2: accepts a hash (default SM3) and nothing else.
Encrypting and Decrypting¶
The primary interface for encryption is
-
class PK_Encryptor¶
-
std::vector<uint8_t> encrypt(const uint8_t in[], size_t length, RandomNumberGenerator &rng) const¶
-
std::vector<uint8_t> encrypt(std::span<const uint8_t> in, RandomNumberGenerator &rng) const¶
These encrypt a message, returning the ciphertext.
-
size_t maximum_input_size() const¶
Returns the maximum size of the message that can be processed, in bytes. If you call
PK_Encryptor::encryptwith a value larger than this the operation will fail with an exception.
-
size_t ciphertext_length(size_t ctext_len) const¶
Return an upper bound on the returned size of a ciphertext, if this particular key/padding scheme is used to encrypt a message of the provided length.
-
std::vector<uint8_t> encrypt(const uint8_t in[], size_t length, RandomNumberGenerator &rng) const¶
PK_Encryptor is only an interface - to actually encrypt you have to
create an implementation, of which there are currently three available in the
library, PK_Encryptor_EME, DLIES_Encryptor and
ECIES_Encryptor. DLIES is a hybrid encryption scheme (from
IEEE 1363) that uses Diffie-Hellman key agreement technique in combination with
a KDF, a MAC and a symmetric encryption algorithm to perform message
encryption. ECIES is similar to DLIES, but uses ECDH for the key
agreement. Normally, public key encryption is done using algorithms which
support it directly, such as RSA or ElGamal; these use the EME class:
-
class PK_Encryptor_EME¶
-
PK_Encryptor_EME(const Public_Key &key, RandomNumberGenerator &rng, const PK_Encryption_Options &options)¶
With key being the key you want to encrypt messages to, configured as described by options (see Encryption Options).
The passed rng object must outlive any PK operations object created using it.
If you are not sure what padding to use, use
PK_Encryption_Options().with_padding("OAEP").with_hash("SHA-256"). If you need compatibility with protocols using the PKCS #1 v1.5 standard, you can also usewith_padding("PKCS1v15").For SM2 encryption, only a hash may be specified; normally it is left at the default of SM3.
-
PK_Encryptor_EME(const Public_Key &key, RandomNumberGenerator &rng, std::string_view padding, std::string_view provider = "")¶
The padding method to use is specified by the string padding, which is the interface available in previous versions of Botan. The string is translated into the equivalent
PK_Encryption_Options; new code should prefer to construct the options directly.For RSA and ElGamal the string names a padding scheme, for example “OAEP(SHA-256)” or “PKCS1v15”. For SM2 encryption, the padding string specifies which hash function to use; normally this would be “SM3”.
-
PK_Encryptor_EME(const Public_Key &key, RandomNumberGenerator &rng, const PK_Encryption_Options &options)¶
-
class DLIES_Encryptor¶
Deprecated since version 2.13.0: DLIES should no longer be used
Available in the header
dlies.h-
DLIES_Encryptor(const DH_PrivateKey &own_priv_key, RandomNumberGenerator &rng, std::unique_ptr<KDF> kdf, std::unique_ptr<MessageAuthenticationCode> mac, size_t mac_key_len = 20)¶
Where kdf is a key derivation function (see Key Derivation Functions (KDF)) and mac is a MessageAuthenticationCode. The encryption is performed by XORing the message with a stream of bytes provided by the KDF.
-
DLIES_Encryptor(const DH_PrivateKey &own_priv_key, RandomNumberGenerator &rng, std::unique_ptr<KDF> kdf, std::unique_ptr<Cipher_Mode> cipher, size_t cipher_key_len, std::unique_ptr<MessageAuthenticationCode> mac, size_t mac_key_len = 20)¶
Instead of XORing the message with KDF output, a cipher mode can be used
-
DLIES_Encryptor(const DH_PrivateKey &own_priv_key, RandomNumberGenerator &rng, std::unique_ptr<KDF> kdf, std::unique_ptr<MessageAuthenticationCode> mac, size_t mac_key_len = 20)¶
-
class ECIES_Encryptor¶
Available in the header
ecies.h.Warning
ECIES is standardized by various organizations (including IEEE and ISO) but unfortunately has dozens of different options which greatly hinder interoperability. ECDH key exchange with a static receiver key is much simpler, and provides similar security properties.
Prefer HPKE in new systems.
Parameters for encryption and decryption are set by the
ECIES_System_Paramsclass which stores the EC domain parameters, the KDF (see Key Derivation Functions (KDF)), the cipher (see Cipher Modes) and the MAC.-
ECIES_Encryptor(const PK_Key_Agreement_Key &private_key, const ECIES_System_Params &ecies_params, RandomNumberGenerator &rng)¶
Where private_key is the key to use for the key agreement. The system parameters are specified in ecies_params and the RNG to use is passed in rng.
-
ECIES_Encryptor(RandomNumberGenerator &rng, const ECIES_System_Params &ecies_params)¶
Creates an ephemeral private key which is used for the key agreement.
-
void ECIES_Encryptor::set_initialization_vector(const InitializationVector &iv)¶
Set a new initialization vector for the encryptor. This must be called before each message with a random nonce suitable for the chosen cipher. In the ECIES message format the nonce is not conveyed with the produced ciphertext, so it must be set separately.
Warning
The ECIES specification has a flaw that the initialization vector is not authenticated. If ECIES is used with a CBC mode cipher, an attacker can trivially modify ciphertexts by flipping bits, and may also be able to mount a padding oracle attack. To avoid this only use ECIES with an AEAD mode such as GCM, or additionally authenticate the IV by including it in the value passed to set_label. Alternately, use HPKE.
-
void ECIES_Encryptor::set_label(std::string_view label)¶
Provide some additional data which is authenticated along with the ciphertext.
-
ECIES_Encryptor(const PK_Key_Agreement_Key &private_key, const ECIES_System_Params &ecies_params, RandomNumberGenerator &rng)¶
-
class PK_Decryptor¶
Interface for public key decryption.
-
secure_vector<uint8_t> decrypt(std::span<const uint8_t> in) const¶
Decrypts a message, throwing an exception in the case of failure.
Warning
If using PKCS1v1.5 encryption padding this function is not safe since it exposes via a side channel if the decryption succeeded or not. This side channel is sufficient for an attacker to decrypt arbitrary messages and forge arbitrary signatures. Use
PK_Decryptor::decrypt_or_randomto avoid this situation.
-
secure_vector<uint8_t> decrypt_or_random(const uint8_t in[], size_t length, size_t expected_pt_len, RandomNumberGenerator &rng) const¶
Similar to decrypt except that if the decryption fails, or if the decrypted key is not of the expected length, then it returns a random string of the expected length. This hides the PKCS1v1.5 oracle.
-
secure_vector<uint8_t> decrypt_or_random(const uint8_t in[], size_t length, size_t expected_pt_len, RandomNumberGenerator &rng, const uint8_t required_content_bytes[], const uint8_t required_content_offsets[], size_t required_contents) const¶
Similar to decrypt except that if the decryption fails, or if the decrypted key is not of the expected length, then it returns a random string of the expected length. This hides the PKCS1v1.5 oracle.
This variant of the function is used if there are specific bytes within the message which must take on a certain value, rather than the encrypted “message” just being a random key, which is the more typical usage. If any of the required values are incorrect, then again a randomly generated key is returned to hide the PKCS1v1.5 oracle.
-
secure_vector<uint8_t> decrypt(std::span<const uint8_t> in) const¶
-
class PK_Decryptor_EME¶
The decryption counterpart of
PK_Encryptor_EME, for RSA, ElGamal and SM2.-
PK_Decryptor_EME(const Private_Key &key, RandomNumberGenerator &rng, const PK_Encryption_Options &options)¶
Construct a decryptor for key. The options must be the same as those used to create the ciphertext (see Encryption Options).
The passed rng object must outlive any PK operations object created using it.
-
PK_Decryptor_EME(const Private_Key &key, RandomNumberGenerator &rng, std::string_view padding, std::string_view provider = "")¶
Construct a decryptor using a padding string, which is translated into the equivalent
PK_Encryption_Optionsexactly as forPK_Encryptor_EME.The passed rng object must outlive any PK operations object created using it.
-
PK_Decryptor_EME(const Private_Key &key, RandomNumberGenerator &rng, const PK_Encryption_Options &options)¶
Botan implements the following encryption algorithms. The string parameter each accepts in the string based constructors is described below; the equivalent options are listed in Encryption Options.
RSA. Requires a padding scheme as parameter.
DLIES (deprecated)
ECIES
SM2. Takes an optional
HashFunctionas parameter which defaults to SM3.ElGamal. Requires a padding scheme as parameter.
Code Example: RSA Encryption¶
The following code sample reads a PKCS #8 keypair from the passed location and subsequently encrypts a fixed plaintext with the included public key, using OAEP with SHA-256. For the sake of completeness, the ciphertext is then decrypted using the private key.
#include <botan/auto_rng.h>
#include <botan/hex.h>
#include <botan/pk_keys.h>
#include <botan/pkcs8.h>
#include <botan/pubkey.h>
#include <botan/rng.h>
#include <iostream>
int main(int argc, char* argv[]) {
if(argc != 2) {
return 1;
}
const std::string_view plaintext(
"Your great-grandfather gave this watch to your granddad for good luck. "
"Unfortunately, Dane's luck wasn't as good as his old man's.");
const Botan::secure_vector<uint8_t> pt(plaintext.data(), plaintext.data() + plaintext.length());
Botan::AutoSeeded_RNG rng;
// load keypair
Botan::DataSource_Stream in(argv[1]);
auto kp = Botan::PKCS8::load_key(in);
// set up the encryption options
const auto enc_options = Botan::PK_Encryption_Options().with_padding("OAEP").with_hash("SHA-256");
// encrypt with pk
const Botan::PK_Encryptor_EME enc(*kp, rng, enc_options);
const auto ct = enc.encrypt(pt, rng);
// decrypt with sk
const Botan::PK_Decryptor_EME dec(*kp, rng, enc_options);
const auto pt2 = dec.decrypt(ct);
std::cout << "\nenc: " << Botan::hex_encode(ct) << "\ndec: " << Botan::hex_encode(pt2);
return 0;
}
Available encryption padding schemes¶
Note
Padding schemes in the context of encryption are sometimes also called Encoding Method for Encryption (EME).
OAEP¶
OAEP (called EME1 in IEEE 1363 and in earlier versions of the library) as specified in PKCS#1 v2.0 (RFC 2437) or PKCS#1 v2.1 (RFC 3447).
Name:
OAEP,Deprecated aliases:
EME-OAEP,EME1Parameters specification:
(<HashFunction>)(<HashFunction>,MGF1)(<HashFunction>,MGF1(<HashFunction>))(<HashFunction>,MGF1(<HashFunction>),<optional label>)
The only Mask generation function available is MGF1, which is also the default.
By default the same hash function will be used for the label and MGF1.
By default the OAEP label is the empty string
Examples:
OAEP(SHA-256),OAEP(SHA-256,MGF1),OAEP(SHA-256,MGF1(SHA-512)),OAEP(SHA-512,MGF1(SHA-512),TCPA)With
PK_Encryption_Optionsthe hash, MGF1 hash and label are given usingwith_hash,with_mgf1_hashandwith_contextrespectively;OAEP(SHA-512,MGF1(SHA-512),TCPA)is equivalent towith_padding("OAEP").with_hash("SHA-512").with_context("TCPA").
PKCS #1 v1.5 Type 2 (encryption)¶
PKCS #1 v1.5 Type 2 (encryption) padding.
Name: PKCS1v15
Deprecated alias: EME-PKCS1-v1_5
Warning
PKCS v1.5 encryption padding is prone to oracle attacks (the Bleichenbacher
attack, and the many variations thereof). Avoid it if at all possible. If you
must use it, use PK_Decryptor::decrypt_or_random function which
can hide the decryption failures.
Raw EME¶
Does not change the input during padding. Unpadding will strip leading zero bytes.
Warning
This is extremely unsafe and only necessary in specialized situations. Don’t use this unless you know what you are doing.
Name: Raw
Public Key Signature Schemes¶
Signatures are generated using PK_Signer and verified using
PK_Verifier. Both are configured with a
PK_Signature_Options object, which specifies every detail of how the
signature is formed: the hash function, any padding scheme, the signature
encoding, and so on.
Signature Options¶
Added in version 3.14.0.
-
class PK_Signature_Options¶
Describes how a signature is to be generated or verified. The object is built up in a builder style; each
with_xxxfunction returns a new options object with that option added, so the calls can be chained:auto opts = Botan::PK_Signature_Options() .with_hash("SHA-256") .with_der_encoded_signature(); Botan::PK_Signer signer(key, rng, opts); Botan::PK_Verifier verifier(key, opts);
Every option that is set must be understood and acted upon by the signature scheme in use. If a scheme does not support an option (for example a context for RSA, or a padding scheme for Ed25519) then constructing the
PK_SignerorPK_Verifierthrows an exception which names the offending option(s); an option is never silently ignored. The options are validated when the signer or verifier is constructed, not when they are set.Each option can be set at most once; attempting to set an option a second time throws
Invalid_State.The signer and verifier must be configured compatibly. Most options (the hash, padding, encoding, context, and the prehash options) affect the signature itself and so must match on both sides. The exception is
PK_Signature_Options::with_deterministic_signature, which only affects signature generation and is ignored byPK_Verifier.-
PK_Signature_Options()¶
Creates an empty set of options. This is sufficient for schemes which take no parameters (such as Ed25519, ML-DSA, or XMSS).
-
PK_Signature_Options with_hash(std::string_view hash)¶
Specify the hash function used for signing and verification. Most, but not all, schemes require this; RSA, DSA, ECDSA, ECGDSA, ECKCDSA and GOST 34.10 must be given a hash, while SM2 defaults to SM3 if none is given.
Schemes where the hash is fixed by the key (XMSS, HSS-LMS, SLH-DSA) accept this option only if it names the hash the operation uses, as reported by
PK_Signer::hash_function; so that name can always be passed to a verifier. Note that for SLH-DSA this is the function used to hash the message, which for the larger parameter sets is not the one named in the parameter set (for example SLH-DSA-SHA2-192s reportsSHA-512). Schemes which have no hash function parameter at all (Ed25519, Ed448, ML-DSA) reject it.An empty string is ignored, which allows passing through a possibly-unset user configuration.
-
PK_Signature_Options with_padding(std::string_view padding)¶
Specify a padding scheme. This is only used for RSA, which requires it; see RSA signature padding schemes for the available schemes. All other schemes reject this option.
An empty string is ignored.
-
PK_Signature_Options with_der_encoded_signature(bool der = true)¶
Produce, or expect, a signature encoded as an ASN.1
SEQUENCEof two integers, rather than the default fixed-length concatenation of the two signature elements. This formatting is used in protocols such as TLS and in X.509 certificates.Supported by DSA, ECDSA, ECGDSA, ECKCDSA, GOST 34.10 and SM2; rejected by all other schemes.
-
PK_Signature_Options with_deterministic_signature(bool deterministic = true)¶
Request a deterministic signature, that is one which depends only on the key and the message and not on the random number generator.
Some schemes are always deterministic (for example RSA PKCS #1 v1.5, Ed25519, XMSS, HSS-LMS); these accept the option as it is trivially satisfied. DSA and ECDSA are randomized by default but can produce deterministic signatures using the RFC 6979 nonce derivation; this requires the
rfc6979module, and if it is not included in the build the option is rejected withNot_Implemented. ML-DSA and SLH-DSA use their “hedged” (randomized) variants by default, and this option selects the deterministic variant instead. Schemes which cannot produce a deterministic signature (for example RSA-PSS with a non-zero salt) reject the option.This option is ignored for verification.
-
PK_Signature_Options with_salt_size(size_t salt_size)¶
Specify the size in bytes of the random salt. This applies to RSA with the
PSSandISO_9796_DS2padding schemes, where the salt size otherwise defaults to the output length of the hash function. When verifying aPSSsignature, if a salt size is specified then the signature is only accepted if its salt has exactly that size; otherwise any salt size is accepted. ForISO_9796_DS2the salt size is part of the encoding, so the verifier must use the same size as the signer.ML-DSA also accepts this option, but only if the size equals the 32 bytes of randomness the scheme uses (64 for Dilithium), and not in combination with a deterministic signature.
-
PK_Signature_Options with_context(std::span<const uint8_t> context)¶
-
PK_Signature_Options with_context(std::string_view context)¶
Specify a context which is bound into the signature. Currently this is only supported by SM2, where the context is the user identifier
IDA; if no context is given SM2 uses the default identifier1234567812345678specified in GM/T 0009-2012.
-
PK_Signature_Options with_prehash(std::optional<std::string> prehash = std::nullopt)¶
Request that the library hash the message before signing it, for schemes which normally sign the entire message directly. Ed25519 and Ed448 are such schemes; they sign the full message (which consequently must be buffered in memory), but also define prehashed variants Ed25519ph and Ed448ph. Calling this with no argument selects the scheme’s standard prehash (SHA-512 for Ed25519ph, SHAKE-256(512) for Ed448ph). Naming a hash function instead uses that function; for Ed25519 this selects the hash-then-sign construction used by GnuPG, which is not compatible with Ed25519ph even if SHA-512 is named. See Ed25519 and Ed448 Variants.
The caller still provides the complete message, and the library computes the hash. Schemes which always hash the message as part of signing (DSA, ECDSA, RSA, …) do not offer a separate prehash mode and reject this option, with the exception that DSA, ECDSA, ECGDSA and GOST 34.10 accept it if the named prehash is the same as the signature hash.
This cannot be combined with
PK_Signature_Options::with_externally_computed_prehash.
-
PK_Signature_Options with_externally_computed_prehash(std::optional<std::string> hash = std::nullopt)¶
Specify that the caller has already hashed the message. The data passed to the signer or verifier is then not the message but a digest of it, and is signed (or verified) directly without being hashed again.
Warning
This is intended for situations where the hash is computed by another component and only the digest is available for signing. Many ways of doing this are insecure. Don’t use this unless you know what you are doing.
The hash function the caller used may be named, either as the argument here or using
PK_Signature_Options::with_hash(if both are given they must agree). Naming it allows the scheme to check that the input has the correct length, and to identify the hash in the signature where the format requires it; for example a signature created with RSAPKCS1v15and an externally computed SHA-256 digest is identical to one created over the original message withPKCS1v15andSHA-256. If no hash is named the input is signed as an opaque byte string of any length.This is supported by DSA, ECDSA, ECGDSA, GOST 34.10 (these four require the
raw_hashmodule, and reject the option withLookup_Errorif it is not included in the build), SM2 (where theZAidentifier hash is then not computed and any context is rejected) and RSA with thePKCS1v15orRawpadding schemes. It is rejected by ECKCDSA (whose hash input includes a key-derived prefix), by the RSA padding schemes which must hash the message themselves, and by all other schemes.This cannot be combined with
PK_Signature_Options::with_prehash.
-
PK_Signature_Options with_explicit_trailer_field(bool trailer = true)¶
Use the “explicit” trailer field, which identifies the hash function, rather than the “implicit” one. This only applies to the RSA
ISO_9796_DS2andISO_9796_DS3padding schemes, which default to the explicit trailer; all other schemes reject it.
-
PK_Signature_Options with_provider(std::string_view provider)¶
Request a specific implementation. This is rarely needed.
-
std::string to_string() const¶
Formats the options as a string, for debugging and error messages. The format is not fixed.
-
PK_Signature_Options()¶
Signature Options Accepted by Each Scheme¶
The following summarizes which options each signature scheme accepts; any option not listed is rejected when the signer or verifier is constructed.
RSA: requires a padding scheme, and (except for
Rawpadding) a hash. See RSA signature padding schemes. Additionally accepts a salt size (PSS,ISO_9796_DS2), an explicit trailer field (ISO_9796_DS2,ISO_9796_DS3), an externally computed prehash (PKCS1v15,Raw), and a deterministic signature (PKCS1v15,X9.31,ISO_9796_DS3, andPSSorISO_9796_DS2with a salt size of zero).DSA and ECDSA: require a hash. Accept DER encoding, a deterministic signature (RFC 6979), and an externally computed prehash.
ECGDSA and GOST 34.10: require a hash. Accept DER encoding and an externally computed prehash.
ECKCDSA: requires a hash. Accepts DER encoding.
SM2: accepts a hash (default SM3), a context (the user identifier), DER encoding, and an externally computed prehash.
Ed25519 and Ed448: take no hash. Accept a prehash and a deterministic signature (they are always deterministic).
ML-DSA (and Dilithium): accept a deterministic signature, and a salt size equal to the scheme’s randomness length.
SLH-DSA, XMSS, HSS-LMS: accept a hash only if it names the hash the operation reports, and a deterministic signature (SLH-DSA is randomized by default; XMSS and HSS-LMS are always deterministic).
Signing and Verifying¶
Signature generation is performed using
-
class PK_Signer¶
-
PK_Signer(const Private_Key &key, RandomNumberGenerator &rng, const PK_Signature_Options &options = PK_Signature_Options())¶
Constructs a new signer object for the private key key, configured as described by options (see Signature Options). The key must support signature operations. In the current version of the library, this includes RSA, ECDSA, ML-DSA, ECKCDSA, ECGDSA, SM2, and others.
The passed rng object must outlive any PK operations object created using it.
Most common algorithms, including RSA and ECDSA, require the options to specify at least a hash function (and for RSA, a padding scheme). Schemes without any parameters, such as Ed25519, ML-DSA or XMSS, can be used with the default options.
Any option not supported by the key’s algorithm causes an exception.
-
PK_Signer(const Private_Key &key, RandomNumberGenerator &rng, std::string_view padding, Signature_Format format = Signature_Format::Standard, std::string_view provider = "")¶
Constructs a new signer using the hash/padding specified by the string padding, which is the interface available in previous versions of Botan. The string is translated into the equivalent
PK_Signature_Options; new code should prefer to construct the options directly.The passed rng object must outlive any PK operations object created using it.
The proper value of padding depends on the algorithm. For many signature schemes including ECDSA and DSA, simply naming a hash function like “SHA-256” is all that is required.
For RSA, more complicated padding is required. The two most common schemes for RSA signature padding are PSS and PKCS1v1.5, so you must specify both the padding mechanism as well as a hash, for example “PSS(SHA-256)” or “PKCS1v15(SHA-256)”.
Certain newer signature schemes, especially post-quantum based ones, hardcode the hash function associated with their signatures, and no configuration is possible. In this case padding should be left blank, or may possibly be used to identify some algorithm-specific option. For instance ML-DSA may be parameterized with “Randomized” or “Deterministic” to choose if the generated signature is randomized or not. If left blank, a default is chosen.
Another available option, usable in certain specialized scenarios, is using padding scheme “Raw”, where the provided input is treated as if it was already hashed, and directly signed with no other processing. This corresponds to
PK_Signature_Options::with_externally_computed_prehash.The format defaults to
Standardwhich is either the usual, or the only, available formatting method, depending on the algorithm. For certain signature schemes including ECDSA, DSA, ECGDSA and ECKCDSA you can also useDerSequence, which will format the signature as an ASN.1 SEQUENCE value. This formatting is used in protocols such as TLS and Bitcoin. This corresponds toPK_Signature_Options::with_der_encoded_signature.Note
Botan both supports non-deterministic and deterministic (as per RFC 6979) DSA and ECDSA signatures. Either type of signature can be verified by any other (EC)DSA library, regardless of which mode it prefers. With the string interface, a deterministic signature can be requested by appending “,Deterministic” to the hash name, eg “SHA-256,Deterministic”; this requires the
rfc6979module.
-
void update(const uint8_t *in, size_t length)¶
-
void update(std::span<const uint8_t> in)¶
-
void update(uint8_t in)¶
These add more data to be included in the signature computation. Typically, the input will be provided directly to a hash function.
-
std::vector<uint8_t> signature(RandomNumberGenerator &rng)¶
Creates the signature and returns it. The rng may or may not be used, depending on the scheme.
-
std::vector<uint8_t> sign_message(const uint8_t *in, size_t length, RandomNumberGenerator &rng)¶
-
std::vector<uint8_t> sign_message(std::span<const uint8_t> in, RandomNumberGenerator &rng)¶
These functions are equivalent to calling
PK_Signer::updateand thenPK_Signer::signature. Any data previously provided usingupdatewill also be included in the signature.
-
size_t signature_length() const¶
Return an upper bound on the length of the signatures returned by this object.
-
AlgorithmIdentifier algorithm_identifier() const¶
Return an algorithm identifier appropriate to identify signatures generated by this object in an X.509 structure.
-
std::string hash_function() const¶
Return the hash function which is being used
-
PK_Signer(const Private_Key &key, RandomNumberGenerator &rng, const PK_Signature_Options &options = PK_Signature_Options())¶
Signatures are verified using
-
class PK_Verifier¶
-
PK_Verifier(const Public_Key &pub_key, const PK_Signature_Options &options = PK_Signature_Options())¶
Construct a new verifier for signatures associated with public key pub_key. The options should be the same as those used by the signer (see Signature Options); the deterministic signature option is ignored, as it does not affect verification.
-
PK_Verifier(const Public_Key &pub_key, std::string_view padding, Signature_Format format = Signature_Format::Standard, std::string_view provider = "")¶
Construct a new verifier for signatures associated with public key pub_key. The padding and format should be the same as that used by the signer. As with
PK_Signer, the string is translated into the equivalentPK_Signature_Options.
-
void update(const uint8_t *in, size_t length)¶
-
void update(std::span<const uint8_t> in)¶
-
void update(uint8_t in)¶
Add further message data that is purportedly associated with the signature that will be checked.
-
bool check_signature(const uint8_t *sig, size_t length)¶
-
bool check_signature(std::span<const uint8_t> sig)¶
Check to see if sig is a valid signature for the message data that was written in. Return true if so. This function clears the internal message state, so after this call you can call
PK_Verifier::updateto start verifying another message.
-
bool verify_message(const uint8_t *msg, size_t msg_length, const uint8_t *sig, size_t sig_length)¶
-
bool verify_message(std::span<const uint8_t> msg, std::span<const uint8_t> sig)¶
These are equivalent to calling
PK_Verifier::updateon msg and then callingPK_Verifier::check_signatureon sig. Any data previously provided toPK_Verifier::updatewill also be included.
-
PK_Verifier(const Public_Key &pub_key, const PK_Signature_Options &options = PK_Signature_Options())¶
Botan implements the following signature algorithms. The string parameter each accepts in the string based constructors is described below; the equivalent options are listed in Signature Options.
RSA. Requires a padding scheme as parameter.
DSA. Requires a hash function as parameter.
ECDSA. Requires a hash function as parameter.
ECGDSA. Requires a hash function as parameter.
ECKDSA. Requires a hash function as parameter, not supporting
Raw.GOST 34.10-2001. Requires a hash function as parameter.
Ed25519 and Ed448. See Ed25519 and Ed448 Variants for parameters.
SM2. Takes one of the following as parameter:
<user ID>(usesSM3)<user ID>,<HashFunction>
ML-DSA (Dilithium). Takes the optional parameter
Deterministic(default) orRandomized. ML-DSA additionally accepts an application context string of at most 255 bytes viaPK_Signature_Options::with_context(FIPS 204, Algorithm 2); the same context must be given for verification. The pre-standard Dilithium round 3 variants do not support a context.SLH-DSA. Takes the optional parameter
Deterministic(default) orRandomized.XMSS. Takes no parameter.
HSS-LMS. Takes no parameter.
Code Example: ECDSA Signature¶
The following sample program below demonstrates the generation of a new ECDSA keypair over the curve secp512r1 and a ECDSA signature using SHA-256. Subsequently the computed signature is validated.
#include <botan/auto_rng.h>
#include <botan/ec_group.h>
#include <botan/ecdsa.h>
#include <botan/hex.h>
#include <botan/pubkey.h>
#include <iostream>
int main() {
Botan::AutoSeeded_RNG rng;
// Generate ECDSA keypair
const auto group = Botan::EC_Group::from_name("secp521r1");
const Botan::ECDSA_PrivateKey key(rng, group);
const std::string message("This is a tasty burger!");
// sign data
Botan::PK_Signer signer(key, rng, Botan::PK_Signature_Options().with_hash("SHA-256"));
signer.update(message);
std::vector<uint8_t> signature = signer.signature(rng);
std::cout << "Signature:\n" << Botan::hex_encode(signature);
// now verify the signature
Botan::PK_Verifier verifier(key, Botan::PK_Signature_Options().with_hash("SHA-256"));
verifier.update(message);
std::cout << "\nis " << (verifier.check_signature(signature) ? "valid" : "invalid");
return 0;
}
RSA signature padding schemes¶
These signature padding mechanisms are specific to RSA; no other public key algorithms included in Botan make use of then. For historical reasons, many different padding schemes have been defined for RSA over the years. The most common are PSS and the (now obsolete) PKCS1v15.
Note
Padding schemes in the context of signatures are sometimes also called Encoding methods for signatures with appendix (EMSA).
PKCS #1 v1.5 Type 1 (signature)¶
PKCS #1 v1.5 Type 1 (signature) padding, aka EMSA3 in IEEE 1363.
Note
While not as actively unsafe as PKCS1v15 encryption padding is, PKCS1 signature padding is considered quite obsolete.
Name:
PKCS1v15Deprecated aliases:
EMSA_PKCS1,EMSA-PKCS1-v1_5,EMSA3Parameters specification:
(<HashFunction>)(Raw,<optional HashFunction>)
The raw variant encodes a precomputed hash, optionally with the digest ID of the given hash. With
PK_Signature_Optionsthis is selected usingPK_Signature_Options::with_externally_computed_prehash.Examples:
PKCS1v15(SHA-256),PKCS1v15(Raw),PKCS1v15(Raw,MD5),
Probabilistic signature scheme (PSS)¶
Called EMSA4 in IEEE 1363.
Name:
PSSDeprecated aliases:
EMSA-PSS,PSSR,PSS-MGF1,EMSA4Parameters specification:
(<HashFunction>)(<HashFunction>,MGF1,<optional salt size>)
Examples:
PSS(SHA-256),PSS(SHA-256,MGF1,32),
There also exists a raw version, which accepts a pre-hashed buffer instead of the message. Don’t use this unless you know what you are doing.
Name:
PSS_RawDeprecated alias:
PSSR_RawParameters specification:
(<HashFunction>)(<HashFunction>,MGF1,<optional salt size>)
ISO-9796-2¶
The ISO-9796-2 padding schemes are used for signatures in the EMV contactless payment card system. There is likely no reason to use it in other contexts.
ISO-9796-2 - Digital signature scheme 2 (probabilistic).
Name:
ISO_9796_DS2Parameters specification:
(<HashFunction>)(<HashFunction>,<exp|imp>,<optional salt size>)
Defaults to the explicit mode.
Examples:
ISO_9796_DS2(RIPEMD-160),ISO_9796_DS2(RIPEMD-160,imp)
ISO-9796-2 - Digital signature scheme 3 (deterministic), i.e. DS2 without a salt.
Name:
ISO_9796_DS3Parameters specification:
(<HashFunction>)(<HashFunction>,<exp|imp>
Defaults to the explicit mode.
Examples:
ISO_9796_DS3(RIPEMD-160),ISO_9796_DS3(RIPEMD-160,imp),
X9.31¶
Padding scheme from ANSI X9.31. Called EMSA2 in IEEE 1363.
Deprecated since version 3.7.0: X9.31 signatures are obsolete, and support for it is deprecated
Name:
X9.31Deprecated aliases:
EMSA2,EMSA_X931Parameters specification:
(<HashFunction>)Example:
X9.31(SHA-256)
Raw¶
Sign inputs directly with no hashing or padding
Warning
This exists as an escape hatch allowing an application to define some protocol-specific padding scheme, and using it in a naive way is completely insecure. Don’t use this unless you know what you are doing.
Name:
RawParameters specification:
(<optional HashFunction>)Examples:
Raw,Raw(SHA-256)With
PK_Signature_Options, the optional hash is given usingPK_Signature_Options::with_externally_computed_prehash.
Signature with Hash¶
For many signature schemes including ECDSA and DSA,
simply naming a hash function like SHA-256 is all that is required.
Note
Previous versions of Botan required using a hash specifier like
EMSA1(SHA-256) when generating or verifying ECDSA/DSA signatures, with
the specified hash. The EMSA1 was a reference to a now obsolete IEEE
standard.
Parameters specification:
<HashFunction>EMSA1(<HashFunction>)[deprecated]
There also exists a raw mode, which accepts a pre-hashed buffer instead of the message.
Warning
This is used for situations where somehow the hash is computed by another module and then signed. Many ways of doing this are insecure. Don’t use this unless you know what you are doing.
Parameters specification:
RawRaw(<HashFunction>)
With PK_Signature_Options, this mode is selected using
PK_Signature_Options::with_externally_computed_prehash.
Ed25519 and Ed448 Variants¶
Warning
Ed25519 and Ed448 have different verification criteria, depending on the implementation. This can be problematic in systems which rely on consensus - see It’s 255:19AM. Do you know what your validation criteria are? for details.
Most signature schemes in Botan follow a hash-then-sign paradigm. That is, the entire message is digested to a fixed length representative using a collision resistant hash function, and then the digest is signed. Ed25519 and Ed448 instead sign the message directly. This is beneficial, in that the design should remain secure even in the (extremely unlikely) event that a collision attack on SHA-512 is found. However it means the entire message must be buffered in memory, which can be a problem for many applications which might need to sign large inputs. To use this variety of Ed25519/Ed448, use a padding name of “Pure”.
This is the default mode if no padding name is given.
Parameter specification:
Pure / Identity
Ed25519ph (or Ed448) (pre-hashed) instead hashes the message with SHA-512 (or SHAKE256(512))
and then signs the digest plus a special prefix specified in RFC 8032. To use it, specify
padding name “Ed25519ph” (or “Ed448ph”), or with PK_Signature_Options
call PK_Signature_Options::with_prehash with no argument.
Parameter specification:
Ed25519ph
Another variant of pre-hashing is used by GnuPG. There the message is digested
with any hash function, then the digest is signed. To use it, specify any valid
hash function (or pass its name to PK_Signature_Options::with_prehash).
Even if SHA-512 is used, this variant is not compatible with Ed25519ph.
Parameter specification:
<HashFunction>
For best interop with other systems, prefer “Ed25519ph”.
Key Agreement¶
Key agreement is a scheme where two parties exchange public keys, after which it is possible for them to derive a secret key which is known only to the two of them.
There are different approaches possible for key agreement. In many protocols, both parties generate a new key, exchange public keys, and derive a secret, after which they throw away their private keys, using them only the once. However this requires the parties to both be online and able to communicate with each other.
In other protocols, one of the parties publishes their public key online in some way, and then it is possible for someone to send encrypted messages to that recipient by generating a new keypair, performing key exchange with the published public key, and then sending both the message along with their ephemeral public key. Then the recipient uses the provided public key along with their private key to complete the key exchange, recover the shared secret, and decrypt the message.
Typically the raw output of the key agreement function is not uniformly distributed, and may not be of an appropriate length to use as a key. To resolve these problems, key agreement will use a Key Derivation Functions (KDF) on the shared secret to produce an output of the desired length.
ECDH over GF(p) Weierstrass curves
ECDH over x25519 or x448
DH over prime fields
How the agreed value is turned into the shared key is specified using a
PK_Key_Agreement_Options object.
Key Agreement Options¶
Added in version 3.14.0.
-
class PK_Key_Agreement_Options¶
Describes how the shared key is derived from the agreed value. As with
PK_Signature_Options, the object is built up in a builder style; eachwith_xxxfunction returns a new options object with that option added:auto opts = Botan::PK_Key_Agreement_Options().with_kdf("HKDF(SHA-256)"); Botan::PK_Key_Agreement ka(priv_key, rng, opts);
Every option that is set must be understood by the scheme in use, otherwise constructing the
PK_Key_Agreementthrows an exception naming the offending option(s). Each option can be set at most once. Both parties must use the same options to arrive at the same shared key.The agreed value is never a uniformly random key: for ECDH it is the x coordinate of a curve point, for DH a group element, and for X25519/X448 the output of the Montgomery ladder. So, unlike
PK_KEM_Options, there is no usable default; the caller must either specify a KDF or explicitly ask for the raw value, and the default options are rejected.-
PK_Key_Agreement_Options()¶
Creates an empty set of options. These are always rejected; see above.
-
PK_Key_Agreement_Options with_kdf(std::string_view kdf)¶
Derive the shared key from the agreed value using the named key derivation function. The salt and the key length passed to
PK_Key_Agreement::derive_keyare inputs to the KDF, so any length of key can be requested. The name must not be empty.For keys held in a PKCS#11 token the derivation is performed by the token, and this instead names the PKCS#11 key derivation function by its hash (
SHA-256and so on), optionally followed by,Cofactorto select the cofactor variant of the mechanism; see PKCS#11. NamingRawhere is rejected; the raw value is requested withPK_Key_Agreement_Options::with_raw_shared_keyas for any other key. The one exception isRaw,Cofactor, the cofactor variant with raw output, which cannot otherwise be expressed.This cannot be combined with
PK_Key_Agreement_Options::with_raw_shared_key.
Return the agreed value itself as the shared key, without applying a KDF. The key length passed to
PK_Key_Agreement::derive_keyis then ignored (the result has lengthPK_Key_Agreement::agreed_value_size) and no salt may be given. This acknowledges that the application will process the raw value itself, as for example TLS does in its key schedule.This cannot be combined with
PK_Key_Agreement_Options::with_kdf.
-
PK_Key_Agreement_Options with_provider(std::string_view provider)¶
Request a specific implementation. This is rarely needed.
-
std::string to_string() const¶
Formats the options as a string, for debugging and error messages. The format is not fixed.
-
PK_Key_Agreement_Options()¶
Deriving Keys¶
-
class PK_Key_Agreement¶
-
PK_Key_Agreement(const Private_Key &key, RandomNumberGenerator &rng, const PK_Key_Agreement_Options &options)¶
Set up to perform key derivation using the given private key, configured as described by options (see Key Agreement Options).
-
PK_Key_Agreement(const Private_Key &key, RandomNumberGenerator &rng, std::string_view kdf, std::string_view provider = "")¶
Set up to perform key derivation using the given private key and the KDF named by the string kdf, which is the interface available in previous versions of Botan. The string must either name a KDF (equivalent to
PK_Key_Agreement_Options::with_kdf) or be “Raw” (equivalent toPK_Key_Agreement_Options::with_raw_shared_key); an empty string is rejected, as it always has been. New code should prefer to construct the options directly.
-
size_t agreed_value_size() const¶
Return the byte length of what the underlying key agreement outputs. For example ECDH with secp256r1 will return 32, while finite field Diffie-Hellman with a 2048 bit modulus will return 256.
-
SymmetricKey derive_key(size_t key_len, const uint8_t peer_key[], size_t peer_key_len, const uint8_t salt[], size_t salt_len) const¶
-
SymmetricKey derive_key(size_t key_len, std::span<const uint8_t> peer_key, const uint8_t salt[], size_t salt_len) const¶
-
SymmetricKey derive_key(size_t key_len, const uint8_t peer_key[], size_t peer_key_len, const std::string &salt = "") const¶
-
SymmetricKey derive_key(size_t key_len, std::span<const uint8_t> peer_key, const std::string &salt = "") const¶
Return a shared secret key.
The peer_key parameter must be the public key associated with the other party.
The shared key will be of length key_len. If the KDF cannot accommodate outputs of this size (only likely for very large values, or if using KDF1), an exception will be thrown. If a KDF is not in use (the raw shared key was requested), key_len is ignored and this function will always return directly what the agreement scheme output, of length equal to
agreed_value_size.The salt will be hashed along with the shared secret by the KDF; this can be useful to bind the shared secret to a specific usage. If a KDF is not being used then any non-empty salt will be rejected.
-
PK_Key_Agreement(const Private_Key &key, RandomNumberGenerator &rng, const PK_Key_Agreement_Options &options)¶
Code Example: ECDH Key Agreement¶
The code below performs an unauthenticated ECDH key agreement using the secp521r1 elliptic curve and applies the key derivation function KDF2(SHA-256) with 256 bit output length to the computed shared secret.
#include <botan/auto_rng.h>
#include <botan/ec_group.h>
#include <botan/ecdh.h>
#include <botan/hex.h>
#include <botan/pubkey.h>
#include <iostream>
int main() {
Botan::AutoSeeded_RNG rng;
// ec domain and KDF
const auto domain = Botan::EC_Group::from_name("secp521r1");
const auto options = Botan::PK_Key_Agreement_Options().with_kdf("KDF2(SHA-256)");
// the two parties generate ECDH keys
const Botan::ECDH_PrivateKey key_a(rng, domain);
const Botan::ECDH_PrivateKey key_b(rng, domain);
// now they exchange their public values
const auto key_apub = key_a.public_value();
const auto key_bpub = key_b.public_value();
// Construct key agreements and agree on a shared secret
const Botan::PK_Key_Agreement ka_a(key_a, rng, options);
const auto sA = ka_a.derive_key(32, key_bpub).bits_of();
const Botan::PK_Key_Agreement ka_b(key_b, rng, options);
const auto sB = ka_b.derive_key(32, key_apub).bits_of();
if(sA != sB) {
return 1;
}
std::cout << "agreed key:\n" << Botan::hex_encode(sA);
return 0;
}
Key Encapsulation¶
Key encapsulation (KEM) is a variation on public key encryption which is commonly used by post-quantum secure schemes. Instead of choosing a random secret and encrypting it, as in typical public key encryption, a KEM encryption takes no inputs and produces two values, the shared secret and the encapsulated key. The decryption operation takes in the encapsulated key and returns the shared secret.
How the shared secret is turned into the shared key returned to the
application is specified using a PK_KEM_Options object.
KEM Options¶
Added in version 3.14.0.
-
class PK_KEM_Options¶
Describes how the shared key is derived from the KEM’s output. As with
PK_Signature_Options, the object is built up in a builder style; eachwith_xxxfunction returns a new options object with that option added:auto opts = Botan::PK_KEM_Options().with_kdf("HKDF(SHA-256)"); Botan::PK_KEM_Encryptor enc(pub_key, opts); Botan::PK_KEM_Decryptor dec(priv_key, rng, opts);
Every option that is set must be understood by the scheme in use, otherwise constructing the
PK_KEM_EncryptororPK_KEM_Decryptorthrows an exception naming the offending option(s). Each option can be set at most once. The encryptor and decryptor must be configured identically.The raw output of a KEM is not always suitable for direct use as a key. For schemes such as ML-KEM, FrodoKEM and Classic McEliece the output is already a uniformly random string of the right size, and it is returned directly unless a KDF is requested. For others it is not: the output of RSA-KEM or HyMES McEliece is a random group element, and a key agreement scheme used as a KEM (as in the hybrid KEMs used by TLS) produces a group element or a concatenation of secrets. Such schemes reject the default options; the caller must either specify a KDF or explicitly ask for the raw output.
-
PK_KEM_Options()¶
Creates an empty set of options. For KEMs whose output is a uniform key this returns that output; all other KEMs reject it.
-
PK_KEM_Options with_kdf(std::string_view kdf)¶
Derive the shared key from the KEM output using the named key derivation function. The salt and the desired key length passed to the encapsulation and decapsulation functions are inputs to the KDF, so any length of key can be requested. The name must not be empty.
This cannot be combined with
PK_KEM_Options::with_raw_shared_key.
Return the raw output of the KEM as the shared key, without applying a KDF. The desired key length passed to the encapsulation and decapsulation functions is then ignored (the key has the KEM’s fixed output length, see
shared_key_length), and no salt may be given.For KEMs with a uniform output this is the same as the default; for the others it acknowledges that the application will process the raw value itself. The TLS hybrid KEMs support only this option, as TLS hashes the concatenated secrets in its own key schedule.
This cannot be combined with
PK_KEM_Options::with_kdf.
-
PK_KEM_Options with_provider(std::string_view provider)¶
Request a specific implementation. This is rarely needed.
-
std::string to_string() const¶
Formats the options as a string, for debugging and error messages. The format is not fixed.
-
PK_KEM_Options()¶
Encapsulating and Decapsulating¶
-
class PK_KEM_Encryptor¶
-
PK_KEM_Encryptor(const Public_Key &key, const PK_KEM_Options &options)¶
Create a KEM encryptor, configured as described by options (see KEM Options).
-
PK_KEM_Encryptor(const Public_Key &key, std::string_view kdf = "", std::string_view provider = "")¶
Create a KEM encryptor using a string parameter, which is the interface available in previous versions of Botan. The string must either name a KDF (equivalent to
PK_KEM_Options::with_kdf) or be “Raw” (equivalent toPK_KEM_Options::with_raw_shared_key); an empty string is rejected, as it always has been. New code should prefer to construct the options directly.
Size in bytes of the shared key being produced by this PK_KEM_Encryptor.
-
size_t encapsulated_key_length() const¶
Size in bytes of the encapsulated key being produced by this PK_KEM_Encryptor.
-
KEM_Encapsulation encrypt(RandomNumberGenerator &rng, size_t desired_shared_key_len = 32, std::span<const uint8_t> salt = {})¶
Perform a key encapsulation operation with the result being returned as a convenient struct.
-
void encrypt(std::span<uint8_t> out_encapsulated_key, std::span<uint8_t> out_shared_key, RandomNumberGenerator &rng, size_t desired_shared_key_len = 32, std::span<const uint8_t> salt = {})¶
Perform a key encapsulation operation by passing in out-buffers of the correct output length. Use encapsulated_key_length() and shared_key_length() to pre-allocate the output buffers.
-
void encrypt(secure_vector<uint8_t> &out_encapsulated_key, secure_vector<uint8_t> &out_shared_key, size_t desired_shared_key_len, RandomNumberGenerator &rng, std::span<const uint8_t> salt)¶
Perform a key encapsulation operation by passing in out-vectors that will be re-allocated to the correct output size.
-
PK_KEM_Encryptor(const Public_Key &key, const PK_KEM_Options &options)¶
-
class KEM_Encapsulation¶
-
class PK_KEM_Decryptor¶
-
PK_KEM_Decryptor(const Private_Key &key, RandomNumberGenerator &rng, const PK_KEM_Options &options)¶
Create a KEM decryptor. The options must be the same as those used by the encryptor (see KEM Options).
-
PK_KEM_Decryptor(const Private_Key &key, RandomNumberGenerator &rng, std::string_view kdf = "", std::string_view provider = "")¶
Create a KEM decryptor using a string parameter, translated into the equivalent
PK_KEM_Optionsexactly as forPK_KEM_Encryptor.
-
size_t encapsulated_key_length() const¶
Size in bytes of the encapsulated key expected by this PK_KEM_Decryptor.
Size in bytes of the shared key being produced by this PK_KEM_Encryptor.
-
secure_vector<uint8> decrypt(std::span<const uint8> encapsulated_key, size_t desired_shared_key_len, std::span<const uint8_t> salt)¶
Perform a key decapsulation operation
-
void decrypt(std::span<uint8_t> out_shared_key, std::span<const uint8_t> encap_key, size_t desired_shared_key_len = 32, std::span<const uint8_t> salt = {})¶
Perform a key decapsulation operation by passing in a pre-allocated out-buffer. Use shared_key_length() to determine the byte-length required.
-
PK_KEM_Decryptor(const Private_Key &key, RandomNumberGenerator &rng, const PK_KEM_Options &options)¶
Botan implements the following KEM schemes:
RSA (RSA-KEM). The raw output is not a uniform key, so a KDF (or the raw shared key) must be requested explicitly.
ML-KEM (formerly known as Kyber). The raw output is a uniform 32 byte key.
FrodoKEM. The raw output is a uniform key.
Classic McEliece. The raw output is a uniform key.
HyMES McEliece (deprecated). The raw output is not a uniform key.
Code Example: ML-KEM¶
The code below demonstrates key encapsulation using ML-KEM (FIPS 203), formerly known as Kyber.
#include <botan/ml_kem.h>
#include <botan/pubkey.h>
#include <botan/system_rng.h>
#include <iostream>
int main() {
Botan::System_RNG rng;
// To use a salt with ML-KEM, a Key Derivation Function must be specified.
const auto kem_options = Botan::PK_KEM_Options().with_kdf("HKDF(SHA-512)");
const auto salt = rng.random_array<16>();
const size_t shared_key_len = 32;
const Botan::ML_KEM_PrivateKey priv_key(rng, Botan::ML_KEM_Mode::ML_KEM_768);
auto pub_key = priv_key.public_key();
Botan::PK_KEM_Encryptor enc(*pub_key, kem_options);
const auto kem_result = enc.encrypt(rng, shared_key_len, salt);
Botan::PK_KEM_Decryptor dec(priv_key, rng, kem_options);
auto dec_shared_key = dec.decrypt(kem_result.encapsulated_shared_key(), shared_key_len, salt);
if(dec_shared_key != kem_result.shared_key()) {
std::cerr << "Shared keys differ\n";
return 1;
}
return 0;
}
HyMES McEliece cryptosystem¶
McEliece is a cryptographic scheme based on error correcting codes which is thought to be resistant to quantum computers. First proposed in 1978, it is fast and patent-free. Variants have been proposed and broken, but with suitable parameters the original scheme remains secure. However the public keys are quite large, which has hindered deployment in the past.
The implementation of McEliece in Botan was contributed by cryptosource GmbH. It is based on the implementation HyMES, with the kind permission of Nicolas Sendrier and INRIA to release a C++ adaption of their original C code under the Botan license. It was then modified by Falko Strenzke to add side channel and fault attack countermeasures. You can read more about the implementation at http://www.cryptosource.de/docs/mceliece_in_botan.pdf
Encryption in the McEliece scheme consists of choosing a message block of size n, encoding it in the error correcting code which is the public key, then adding t bit errors. The code is created such that knowing only the public key, decoding t errors is intractable, but with the additional knowledge of the secret structure of the code a fast decoding technique exists.
The McEliece implementation in HyMES, and also in Botan, uses an optimization to reduce the public key size, by converting the public key into a systemic code. This means a portion of the public key is a identity matrix, and can be excluded from the published public key. However it also means that in McEliece the plaintext is represented directly in the ciphertext, with only a small number of bit errors. Thus it is absolutely essential to only use McEliece with a CCA2 secure scheme.
The deprecated McEliece implementation only supports the following parameter sets. For a given security level (SL) a McEliece key would use parameters n and t, and have the corresponding key sizes listed:
SL |
n |
t |
public key KB |
private key KB |
|---|---|---|---|---|
80 |
1632 |
33 |
59 |
140 |
107 |
2480 |
45 |
128 |
300 |
128 |
2960 |
57 |
195 |
459 |
147 |
3408 |
67 |
265 |
622 |
191 |
4624 |
95 |
516 |
1234 |
256 |
6624 |
115 |
942 |
2184 |
You can check the speed of McEliece with the suggested parameters above
using botan speed McEliece
Classic McEliece KEM¶
Classic McEliece is an IND-CCA2 secure key encapsulation algorithm based on the McEliece cryptosystem introduced in 1978. It is a code-based scheme that relies on conservative security assumptions and is considered secure against quantum computers. It is an alternative to lattice-based schemes.
Other advantages of Classic McEliece are the small ciphertext size and the fast encapsulation. Key generation and decapsulation are slower than in lattice-based schemes. The main disadvantage of Classic McEliece is the large public key size, ranging from 0.26 MB to 1.36 MB, depending on the instance. Due to its large key size, Classic McEliece is recommended for applications where the public key is stored for a long time, and memory is not a critical resource. Usage with ephemeral keys is not recommended.
Botan’s implementation covers the parameter sets of the NIST round 4 specification and of ISO/IEC 18033-2:2006/Amd 2 (published June 2026), which standardized Classic McEliece. The ISO document itself is not freely available; the official Classic McEliece specification, which the Classic McEliece team states is compatible with the ISO standard, serves as a freely available reference. Botan implements the following parameter sets:
Set without f/pc |
Set with f |
Set with pc |
Set with pcf |
Public Key Size |
|---|---|---|---|---|
mceliece348864 |
mceliece348864f |
0.26 MB |
||
mceliece460896 |
mceliece460896f |
0.52 MB |
||
mceliece6688128 |
mceliece6688128f |
mceliece6688128pc |
mceliece6688128pcf |
1.04 MB |
mceliece6960119 |
mceliece6960119f |
mceliece6960119pc |
mceliece6960119pcf |
1.05 MB |
mceliece8192128 |
mceliece8192128f |
mceliece8192128pc |
mceliece8192128pcf |
1.36 MB |
The instances with the suffix ‘f’ use a faster key generation algorithm that is more consistent in runtime. The instances with the suffix ‘pc’ use plaintext confirmation, which is only specified in the ISO standard. The instances mceliece348864(f) are only defined in the NIST round 4 submission. The ISO standard additionally defines the instances mceliece460896pc(f), which are not currently implemented by Botan.
eXtended Merkle Signature Scheme (XMSS)¶
Botan implements the single tree version of the eXtended Merkle Signature Scheme (XMSS) using Winternitz One Time Signatures+ (WOTS+). The implementation is based on RFC 8391 “XMSS: eXtended Merkle Signature Scheme”.
Warning
XMSS is stateful, meaning the private key updates after each signature
creation. Applications are responsible for updating their persistent secret
with the new output of Private_Key::private_key_bits() after each signature
creation. If the same private key is ever used to generate
two different signatures, then the scheme becomes insecure. For this reason,
it can be challenging to use XMSS securely.
XMSS uses the Botan interfaces for public key cryptography. The following algorithms are implemented:
XMSS-SHA2_10_256
XMSS-SHA2_16_256
XMSS-SHA2_20_256
XMSS-SHA2_10_512
XMSS-SHA2_16_512
XMSS-SHA2_20_512
XMSS-SHAKE_10_256
XMSS-SHAKE_16_256
XMSS-SHAKE_20_256
XMSS-SHAKE_10_512
XMSS-SHAKE_16_512
XMSS-SHAKE_20_512
XMSS-SHA2_10_192
XMSS-SHA2_16_192
XMSS-SHA2_20_192
XMSS-SHAKE256_10_256
XMSS-SHAKE256_16_256
XMSS-SHAKE256_20_256
XMSS-SHAKE256_10_192
XMSS-SHAKE256_16_192
XMSS-SHAKE256_20_192
The algorithm name contains the hash function name, tree height and digest width defined by the corresponding parameter set. Choosing XMSS-SHA2_10_256 for instance will use the SHA2-256 hash function to generate a tree of height ten.
Code Example: XMSS¶
The following code snippet shows a minimum example on how to create an XMSS public/private key pair and how to use these keys to create and verify a signature:
#include <botan/auto_rng.h>
#include <botan/pubkey.h>
#include <botan/secmem.h>
#include <botan/xmss.h>
#include <iostream>
#include <vector>
int main() {
// Create a random number generator used for key generation.
Botan::AutoSeeded_RNG rng;
// create a new public/private key pair using SHA2 256 as hash
// function and a tree height of 10.
const Botan::XMSS_PrivateKey private_key(Botan::XMSS_Parameters::xmss_algorithm_t::XMSS_SHA2_10_256, rng);
const Botan::XMSS_PublicKey& public_key(private_key);
// create Public Key Signer using the private key.
Botan::PK_Signer signer(private_key, rng);
// create and sign a message using the Public Key Signer.
Botan::secure_vector<uint8_t> msg{0x01, 0x02, 0x03, 0x04};
auto sig = signer.sign_message(msg, rng);
// create Public Key Verifier using the public key
Botan::PK_Verifier verifier(public_key);
// verify the signature for the previously generated message.
if(verifier.verify_message(msg, sig)) {
std::cout << "Success.\n";
return 0;
} else {
std::cout << "Error.\n";
return 1;
}
}
Hierarchical Signature System with Leighton-Micali Hash-Based Signatures (HSS-LMS)¶
HSS-LMS is a stateful hash-based signature scheme which is defined in RFC 8554 “Leighton-Micali Hash-Based Signatures”.
It is a multitree scheme, which is highly configurable. Multitree means, it consists of multiple layers of Merkle trees, which can be defined individually. Moreover, the used hash function and the Winternitz Parameter of the underlying one-time signature can be chosen for each tree layer. For a sensible selection of parameters refer to RFC 8554 Section 6.4..
Warning
HSS-LMS is stateful, meaning the private key updates after each signature
creation. Applications are responsible for updating their persistent secret
with the new output of Private_Key::private_key_bits() after each signature
creation. If the same private key is ever used to generate
two different signatures, then the scheme becomes insecure. For this reason,
it can be challenging to use HSS-LMS securely.
HSS-LMS uses the Botan interfaces for public key cryptography. The params
argument of the HSS-LMS private key is used to define the parameter set.
The syntax of this argument must be the following:
HSS-LMS(<hash>,HW(<h>,<w>),HW(<h>,<w>),...)
e.g. HSS-LMS(SHA-256,HW(5,1),HW(5,1)) to use SHA-256 in a two-layer HSS instance
with LMS tree height 5 and Winternitz parameter 1. This results in a
private key that can be used to create up to 2^(5+5)=1024 signatures.
The following parameters are allowed (which are specified in RFC 8554 and and draft-fluhrer-lms-more-parm-sets-11):
hash:
SHA-256,Truncated(SHA-256,192),SHAKE-256(256),SHAKE-256(192)h:
5,10,15,20,25w:
1,2,4,8