PKCS5_PBE_KEYIVGEN(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 PKCS5_PBE_KEYIVGEN — okay so this is the 3ossl manual, bestie

Like, welcome to the PKCS#5 password-based encryption corner of OpenSSL. It's giving "crypto plumbing that actually slaps" and honestly there's a lot of functions here, so grab a snack 🍓 and let's go.

✨ NAME ✨

So the whole squad of functions you're about to meet is:

  • PKCS5_PBE_keyivgen, PKCS5_PBE_keyivgen_ex
  • PKCS5_pbe2_set, PKCS5_pbe2_set_iv, PKCS5_pbe2_set_iv_ex
  • PKCS5_pbe_set, PKCS5_pbe_set_ex
  • PKCS5_pbe2_set_scrypt
  • PKCS5_pbe_set0_algor, PKCS5_pbe_set0_algor_ex
  • PKCS5_v2_PBE_keyivgen, PKCS5_v2_PBE_keyivgen_ex
  • PKCS5_v2_scrypt_keyivgen, PKCS5_v2_scrypt_keyivgen_ex
  • PKCS5_pbkdf2_set, PKCS5_pbkdf2_set_ex
  • EVP_PBE_scrypt, EVP_PBE_scrypt_ex

And collectively they're the PKCS#5 password based encryption routines. That's the vibe 💜

🎀 SYNOPSIS 🎀

Okay so first you gotta pull in the EVP header:

#include <openssl/evp.h>

int PKCS5_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
                       ASN1_TYPE *param, const EVP_CIPHER *cipher,
                       const EVP_MD *md, int en_de);
int PKCS5_PBE_keyivgen_ex(EVP_CIPHER_CTX *cctx, const char *pass, int passlen,
                          ASN1_TYPE *param, const EVP_CIPHER *cipher,
                          const EVP_MD *md, int en_de, OSSL_LIB_CTX *libctx,
                          const char *propq);
int PKCS5_v2_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
                          ASN1_TYPE *param, const EVP_CIPHER *cipher,
                          const EVP_MD *md, int en_de);
int PKCS5_v2_PBE_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
                             ASN1_TYPE *param, const EVP_CIPHER *cipher,
                             const EVP_MD *md, int en_de,
                             OSSL_LIB_CTX *libctx, const char *propq);
int EVP_PBE_scrypt(const char *pass, size_t passlen,
                   const unsigned char *salt, size_t saltlen,
                   uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
                   unsigned char *key, size_t keylen);
int EVP_PBE_scrypt_ex(const char *pass, size_t passlen,
                      const unsigned char *salt, size_t saltlen,
                      uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
                      unsigned char *key, size_t keylen,
                      OSSL_LIB_CTX *ctx, const char *propq);
int PKCS5_v2_scrypt_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass,
                             int passlen, ASN1_TYPE *param,
                             const EVP_CIPHER *c, const EVP_MD *md, int en_de);
int PKCS5_v2_scrypt_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass,
                                int passlen, ASN1_TYPE *param,
                                const EVP_CIPHER *c, const EVP_MD *md, int en_de,
                                OSSL_LIB_CTX *libctx, const char *propq);

Then there's a whole other group that lives in the X.509 header:

#include <openssl/x509.h>

int PKCS5_pbe_set0_algor(X509_ALGOR *algor, int alg, int iter,
                         const unsigned char *salt, int saltlen);
int PKCS5_pbe_set0_algor_ex(X509_ALGOR *algor, int alg, int iter,
                            const unsigned char *salt, int saltlen,
                            OSSL_LIB_CTX *libctx);

X509_ALGOR *PKCS5_pbe_set(int alg, int iter,
                          const unsigned char *salt, int saltlen);
X509_ALGOR *PKCS5_pbe_set_ex(int alg, int iter,
                             const unsigned char *salt, int saltlen,
                             OSSL_LIB_CTX *libctx);

X509_ALGOR *PKCS5_pbe2_set(const EVP_CIPHER *cipher, int iter,
                           unsigned char *salt, int saltlen);
X509_ALGOR *PKCS5_pbe2_set_iv(const EVP_CIPHER *cipher, int iter,
                              unsigned char *salt, int saltlen,
                              unsigned char *aiv, int prf_nid);
X509_ALGOR *PKCS5_pbe2_set_iv_ex(const EVP_CIPHER *cipher, int iter,
                                 unsigned char *salt, int saltlen,
                                 unsigned char *aiv, int prf_nid,
                                 OSSL_LIB_CTX *libctx);
X509_ALGOR *PKCS5_pbe2_set_scrypt(const EVP_CIPHER *cipher,
                                  const unsigned char *salt, int saltlen,
                                  unsigned char *aiv, uint64_t N, uint64_t r,
                                  uint64_t p);

X509_ALGOR *PKCS5_pbkdf2_set(int iter, unsigned char *salt, int saltlen,
                             int prf_nid, int keylen);
X509_ALGOR *PKCS5_pbkdf2_set_ex(int iter, unsigned char *salt, int saltlen,
                                int prf_nid, int keylen,
                                OSSL_LIB_CTX *libctx);

🌸 DESCRIPTION 🌸

🔑 Key Derivation

PKCS5_PBE_keyivgen() and PKCS5_PBE_keyivgen_ex() take a password pass of length passlen, parameters param, and a message digest function md_type, and do a key derivation according to PKCS#5 PBES1. Then that resulting key gets used to initialise the cipher context ctx with a cipher cipher — either for encryption (en_de=1) or decryption (en_de=0). Slay 🔥

pass is optional bestie, it can literally be NULL. And if passlen is -1, the function will just go ahead and calculate the length of pass itself using strlen().

PKCS5_v2_PBE_keyivgen() and PKCS5_v2_PBE_keyivgen_ex() are basically the same thing but they use PKCS#5 PBES2 as the encryption algorithm instead, with the parameters you supply.

PKCS5_v2_scrypt_keyivgen() and PKCS5_v2_scrypt_keyivgen_ex() use SCRYPT as the key derivation part of the encryption algorithm. Valid.

Okay so salt is the salt used in the derivation, and its length is saltlen. Heads up: if the salt is NULL, then saltlen must be 0. And the function will not try to calculate the length of the salt, because it doesn't assume the salt is NULL terminated. No cap.

iter is the iteration count and its value should be greater than or equal to 1. RFC 2898 suggests an iteration count of at least 1000 btw. Any iter less than 1 is treated as a single iteration.

digest is the message digest function used in the derivation.

aiv is the initialization vector (IV) to use for the encryption algorithm. If aiv is NULL, then a random IV will be generated. Iconic ✨

prf_nid is the numeric identifier (NID) for the pseudo-random function to use with PBKDF2. If prf_nid isn't specified (like, for example, when prf_nid is set to 0), a default PRF is used, which is currently set to SHA-256 (NID_hmacWithSHA256).

Functions ending in _ex() take optional parameters libctx and propq, which are used to select appropriate algorithm implementations. Very "pick your own adventure" of them 🦋

🎀 Algorithm Identifier Creation

PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(), PKCS5_pbe2_set_iv_ex() and PKCS5_pbe2_set_scrypt() generate an X509_ALGOR object. That object represents an AlgorithmIdentifier containing the algorithm OID and associated parameters for the PBE algorithm. These functions encode the key derivation parameters (like salt and iteration count) and the encryption parameters (like the IV) into the ASN.1 structure. It's giving "packing a little suitcase" 🧳

PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() generate an X509_ALGOR object representing an AlgorithmIdentifier containing the algorithm OID and associated parameters for the PBKDF2 algorithm.

PKCS5_pbe_set0_algor() and PKCS5_pbe_set0_algor_ex() set the PBE algorithm OID and parameters into the X509_ALGOR you supply.

Okay and about that salt again — if salt is NULL, then saltlen specifies the size in bytes of the random salt to generate. If saltlen is 0 then a default size is used. And the defaults are:

  • For PBE related functions such as PKCS5_pbe_set_ex() the default salt length is 8 bytes.
  • For PBE2 related functions that use PBKDF2 such as PKCS5_pbkdf2_set(), PKCS5_pbe2_set_scrypt() and PKCS5_pbe2_set() the default salt length is 16 bytes.

💀 NOTES 💀

The *_keyivgen() functions are typically used in PKCS#12 to encrypt objects. iykyk.

These functions make no assumption regarding the given password. It will simply be treated as a byte sequence. Like, don't come in here expecting it to be a cute little UTF-8 string, it's just bytes fr fr 🙈

🌈 RETURN VALUES 🌈

  • PKCS5_PBE_keyivgen(), PKCS5_v2_PBE_keyivgen(), PKCS5_v2_PBE_keyivgen_ex(), PKCS5_v2_scrypt_keyivgen(), PKCS5_v2_scrypt_keyivgen_ex(), PKCS5_pbe_set0_algor() and PKCS5_pbe_set0_algor_ex() return 1 for success and 0 if an error occurs.
  • PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(), PKCS5_pbe2_set_iv_ex(), PKCS5_pbe2_set_scrypt(), PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() return an X509_ALGOR object, or NULL if an error occurs. 😭

👑 CONFORMING TO 👑

IETF RFC 8018 (<https://tools.ietf.org/html/rfc8018) — go off, standards queen 💅

🦋 SEE ALSO 🦋

⭐ HISTORY ⭐

PKCS5_v2_PBE_keyivgen_ex(), EVP_PBE_scrypt_ex(), PKCS5_v2_scrypt_keyivgen_ex(), PKCS5_pbe_set0_algor_ex(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set_iv_ex() and PKCS5_pbkdf2_set_ex() were added in OpenSSL 3.0.

From OpenSSL 3.0 the PBKDF1 algorithm used in PKCS5_PBE_keyivgen() and PKCS5_PBE_keyivgen_ex() has been moved to the legacy provider as an EVP_KDF. So yeah, it's living in the legacy wing of the house now 🏚️

In OpenSSL 3.2 the default salt length changed from 8 bytes to 16 bytes for PBE2 related functions such as PKCS5_pbe2_set(). This is required for PBKDF2 FIPS compliance. Important glow-up, not just for aesthetics.

Copyright 2021-2026 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

Not me writing a whole love letter to key derivation 💖 but like, read the license, fr fr, it's literally the law.

And that's the tea bestie — this was OpenSSL 3.5.6, dated 2026-04-07, page PKCS5_PBE_KEYIVGEN(3ossl), signing off 🎀✨🦋

📦 where this page comes from