PKCS12_KEY_GEN_UTF8_EX(3SSL)

📦

version 4.0.3 · 13 versions

💖 PKCS12_KEY_GEN_UTF8_EX 💖

okay so bestie, welcome to the PKCS12_KEY_GEN_UTF8_EX(3SSL) page — it's an OpenSSL joint, and it's all about PKCS#12 Password based key derivation. 🎀

The whole fam is here: PKCS12_key_gen_asc, PKCS12_key_gen_asc_ex, PKCS12_key_gen_uni, PKCS12_key_gen_uni_ex, PKCS12_key_gen_utf8, and PKCS12_key_gen_utf8_ex. Six icons, one job. 👑

✨ SYNOPSIS ✨

#include <openssl/pkcs12.h>

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 like, these methods do a key derivation per PKCS#12 (that's RFC7292, for the girlies taking notes 📝). You feed them:

a password pass that's passlen long,
a salt salt that's saltlen long,
an iteration count iter,
and a digest algorithm md_type.

And the ID byte id decides what the resulting key is for, bestie:

If ID=1, the pseudorandom bits being produced are gonna be used as key material for performing encryption or decryption. 🔐
If ID=2, the pseudorandom bits being produced are gonna be used as an IV (Initial Value) for encryption or decryption. 🌈
If ID=3, the pseudorandom bits being produced are gonna be used as an integrity key for MACing. 🫶

And the format of the password you hand over? That's fully determined by which method you picked:

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.

Now the deets on each param, because we do NOT skimp on details in this house:

pass — the password used in the derivation, of length passlen. It's optional, babes, it can be NULL. And if passlen is -1, the function will calculate the length of pass using strlen(). so convenient tbh ✨
salt — the salt used in the derivation, of length saltlen. If the salt is NULL, then saltlen must be 0. and no, it will not try to measure the salt for you, because it's not assumed to be NULL terminated. it said mind your business 💅
iter — 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.
digest — the message digest function used in the derivation.
out — the derived key gets written here. the size of the out buffer is specified via n.

And the glow-up: functions ending in _ex() let you use a library context ctx and a property query propq to select algorithm implementations. main character energy fr fr. 👑

📝 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.

Also, cranking up 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... turn it up, bestie. it's giving security. 🔥

🫶 RETURN VALUES 🫶

Returns 1 on success or 0 on error. That's it, that's the whole vibe check. ✅

🌈 CONFORMING TO 🌈

IETF RFC 7292 (<https://tools.ietf.org/html/rfc7292>)

💜 HISTORY 💜

PKCS12_key_gen_asc_ex(), PKCS12_key_gen_uni_ex() and PKCS12_key_gen_utf8_ex() were added in OpenSSL 3.0. the _ex girlies are the new kids, and we love them. 🎀

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

okay that's the whole page bestie, go forth and derive some keys 💖✨ this was OpenSSL 4.0.3, dated 2026-09-29 — slay, periodt, no cap. 🦋

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

PKCS12_KEY_GEN_UTF8_EX(3SSL)