Botan 3.14.1
Crypto and TLS for C&
pkcs12_kdf.h
Go to the documentation of this file.
1/*
2* PKCS#12 KDF (RFC 7292 Appendix B)
3* (C) 2026 Damiano Mazzella
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_PKCS12_KDF_H_
9#define BOTAN_PKCS12_KDF_H_
10
11#include <botan/hash.h>
12#include <botan/pwdhash.h>
13#include <botan/types.h>
14
15#include <memory>
16#include <span>
17#include <string>
18
19namespace Botan {
20
21/**
22* PKCS#12 KDF (RFC 7292 Appendix B)
23*
24* The id parameter (purpose byte) is fixed at family construction time:
25* 1 = encryption key, 2 = IV, 3 = MAC key
26*
27* The family spec used with PasswordHashFamily::create() is
28* "PKCS12-KDF(hash,id)", e.g. "PKCS12-KDF(SHA-1,1)" with two arguments.
29* PKCS12_KDF::to_string() additionally embeds the iteration count for
30* round-tripping a fully-parameterized instance, producing
31* "PKCS12-KDF(hash,id,iterations)"; that 3-argument form is not accepted
32* by PasswordHashFamily::create() and should not be used as an algo spec.
33*/
34class PKCS12_KDF final : public PasswordHash {
35 public:
36 PKCS12_KDF(std::unique_ptr<HashFunction> hash, uint8_t id, size_t iterations);
37
38 std::string to_string() const override;
39
40 size_t iterations() const override { return m_iterations; }
41
42 void derive_key(uint8_t out[],
43 size_t out_len,
44 const char* password,
45 size_t password_len,
46 const uint8_t salt[],
47 size_t salt_len) const override;
48
49 private:
50 std::unique_ptr<HashFunction> m_hash;
51 uint8_t m_id;
52 size_t m_iterations;
53};
54
55/**
56* Low-level PKCS#12 KDF (RFC 7292 Appendix B).
57*
58* Runs the KDF on a caller-supplied @p pwd_bytes buffer without applying
59* @c pkcs12_encode_password. Intended for the very rare case (e.g. OpenSSL
60* empty-password interop) where the RFC 7292 UCS-2 BE encoding + null
61* terminator is not the desired input. Normal callers should use the
62* PKCS12_KDF class.
63*/
64BOTAN_TEST_API void pkcs12_kdf(std::span<uint8_t> out,
65 std::span<const uint8_t> pwd_bytes,
66 std::span<const uint8_t> salt,
67 size_t iterations,
68 uint8_t id,
69 HashFunction& hash);
70
72 public:
73 PKCS12_KDF_Family(std::unique_ptr<HashFunction> hash, size_t id);
74
75 std::string name() const override;
76
77 std::unique_ptr<PasswordHash> tune_params(size_t output_length,
78 uint64_t desired_runtime_msec,
79 std::optional<size_t> max_memory_usage_mb = {},
80 uint64_t tuning_msec = 10) const override;
81
82 std::unique_ptr<PasswordHash> default_params() const override;
83
84 std::unique_ptr<PasswordHash> from_iterations(size_t iterations) const override;
85
86 std::unique_ptr<PasswordHash> from_params(size_t i1, size_t i2 = 0, size_t i3 = 0) const override;
87
88 private:
89 std::unique_ptr<HashFunction> m_hash;
90 uint8_t m_id;
91};
92
93} // namespace Botan
94
95#endif
#define BOTAN_TEST_API
Definition api.h:41
std::string name() const override
std::unique_ptr< PasswordHash > from_params(size_t i1, size_t i2=0, size_t i3=0) const override
std::unique_ptr< PasswordHash > tune_params(size_t output_length, uint64_t desired_runtime_msec, std::optional< size_t > max_memory_usage_mb={}, uint64_t tuning_msec=10) const override
std::unique_ptr< PasswordHash > default_params() const override
std::unique_ptr< PasswordHash > from_iterations(size_t iterations) const override
PKCS12_KDF_Family(std::unique_ptr< HashFunction > hash, size_t id)
void derive_key(uint8_t out[], size_t out_len, const char *password, size_t password_len, const uint8_t salt[], size_t salt_len) const override
std::string to_string() const override
PKCS12_KDF(std::unique_ptr< HashFunction > hash, uint8_t id, size_t iterations)
size_t iterations() const override
Definition pkcs12_kdf.h:40
void hash(std::span< uint8_t > out, std::string_view password, std::span< const uint8_t > salt) const
Definition pwdhash.h:95
void pkcs12_kdf(std::span< uint8_t > out, std::span< const uint8_t > pwd_bytes, std::span< const uint8_t > salt, size_t iterations, uint8_t id, HashFunction &hash)