PKCS12_KEY_GEN_UTF8_EX(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💖 PKCS12_KEY_GEN_UTF8_EX 💖

okay so this is an OpenSSL manual page, bestie — specifically the 3ossl one — and it's all about PKCS#12 Password based key derivation. yes, that PKCS#12. RFC7292 energy. let's get into it ✨

🌸 NAME 🌸

PKCS12_key_gen_asc, PKCS12_key_gen_asc_ex, PKCS12_key_gen_uni, PKCS12_key_gen_uni_ex, PKCS12_key_gen_utf8, PKCS12_key_gen_utf8_ex — PKCS#12 Password based key derivation. that's the whole squad, six of them, all iconic 👑

✨ SYNOPSIS ✨

like, literally just include the header first:

#include <openssl/pkcs12.h>

and then the whole lineup, no cap:

int PKCS12_key_gen_asc(const char *pass, int passlen, unsigned char *salt,
                       int saltlen, int id, int iter, int n,
                       unsigned char *out, const EVP_MD *md_type);
int PKCS12_key_gen_asc_ex(const char *pass, int passlen, unsigned char *salt,
                          int saltlen, int id, int iter, int n,
                          unsigned char *out, const EVP_MD *md_type,
                          OSSL_LIB_CTX *ctx, const char *propq);
int PKCS12_key_gen_uni(unsigned char *pass, int passlen, unsigned char *salt,
                       int saltlen, int id, int iter, int n,
                       unsigned char *out, const EVP_MD *md_type);
int PKCS12_key_gen_uni_ex(unsigned char *pass, int passlen, unsigned char *salt,
                          int saltlen, int id, int iter, int n,
                          unsigned char *out, const EVP_MD *md_type,
                          OSSL_LIB_CTX *ctx, const char *propq);
int PKCS12_key_gen_utf8(const char *pass, int passlen, unsigned char *salt,
                        int saltlen, int id, int iter, int n,
                        unsigned char *out, const EVP_MD *md_type);
int PKCS12_key_gen_utf8_ex(const char *pass, int passlen, unsigned char *salt,
                           int saltlen, int id, int iter, int n,
                           unsigned char *out, const EVP_MD *md_type,
                           OSSL_LIB_CTX *ctx, const char *propq);

🦋 DESCRIPTION 🦋

so these methods do a key derivation according to PKCS#12 (RFC7292). you feed them:

  • a password pass of length passlen
  • a salt salt of length saltlen
  • an iteration count iter
  • a digest algorithm md_type

and the ID byte id decides what the resulting key is for. it's giving "choose your fighter" 🌈

  • 🎀 If ID=1, then the pseudorandom bits being produced are to be used as key material for performing encryption or decryption.
  • 💜 If ID=2, then the pseudorandom bits being produced are to be used as an IV (Initial Value) for encryption or decryption.
  • 🔥 If ID=3, then the pseudorandom bits being produced are to be used as an integrity key for MACing.

🧚 the password format vibe check

the intended format of the password you hand over depends on which method you picked, and yes this matters:

  • PKCS12_key_gen_asc() and PKCS12_key_gen_asc_ex() expect an ASCII-formatted password.
  • PKCS12_key_gen_uni() and PKCS12_key_gen_uni_ex() expect a Unicode-formatted password.
  • PKCS12_key_gen_utf8() and PKCS12_key_gen_utf8_ex() expect a UTF-8 encoded password.

🍓 the parameters, one by one

pass is the password used in the derivation, of length passlen. it's an optional parameter and can be NULL. and if passlen is -1, then the function will calculate the length of pass using strlen(). she does the math for you 💅

salt is the salt used in the derivation, of length saltlen. if the salt is NULL, then saltlen must be 0. the function will not attempt to calculate the length of the salt, because it is not assumed to be NULL terminated. so don't come for her, she's not guessing 🙈

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. any iter less than 1 is treated as a single iteration. so like, 0 and negative numbers get rounded up to "one (1) whole iteration" and honestly? generous.

digest is the message digest function used in the derivation.

the derived key will be written to out. the size of the out buffer is specified via n. 🫶

⭐ the _ex() glow-up

functions ending in _ex() allow for a library context ctx and property query propq to be used to select algorithm implementations. that's the whole difference. main character energy only.

👑 NOTES 👑

a typical application of this function is to derive keying material for an encryption algorithm from a password in the pass, a salt in salt, and an iteration count. classic.

increasing the iter parameter slows down the algorithm, which makes it harder for an attacker to perform a brute force attack using a large number of candidate passwords. so like — higher number, more pain for the hacker, less sleep for your CPU. it's giving sacrifice for the greater good 💀🔥

🌈 RETURN VALUES 🌈

Returns 1 on success or 0 on error. that's it. that's the whole section. binary queen 💅

💜 CONFORMING TO 💜

IETF RFC 7292 (<https://tools.ietf.org/html/rfc7292>) — go read it if you're feeling academic 🎀

🦋 SEE ALSO 🦋

all linked, all friends, all worth the read ✨

🌸 HISTORY 🌸

PKCS12_key_gen_asc_ex(), PKCS12_key_gen_uni_ex() and PKCS12_key_gen_utf8_ex() were added in OpenSSL 3.0. so the _ex() girlies are the new kids. periodt.

Copyright 2021 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>.

ngl legal text is the one place we stay serious — read the license, bestie 🫶

and that's a wrap! this page came from OpenSSL 3.5.6, dated 2026-04-07, filed under PKCS12_KEY_GEN_UTF8_EX(3ossl) — go derive some keys, slay, and hydrate 💅✨🎀

📦 where this page comes from