PKCS12_CREATE(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💖 PKCS12_CREATE(3ossl) — like, the OpenSSL manual, but make it make sense 💖

okay bestie, so you know how certificates and keys need to be bundled up all cute and portable? That's literally what this is. PKCS12_create, PKCS12_create_ex, PKCS12_create_cb, and PKCS12_create_ex2 are the glow-up functions that build you a shiny PKCS#12 structure. This is from the OpenSSL manual, section 3ossl, and trust — by the end you'll be obsessed. 🎀

🌸 SYNOPSIS 🌸

#include <openssl/pkcs12.h>

PKCS12 *PKCS12_create(const char *pass, const char *name, EVP_PKEY *pkey,
                      X509 *cert, STACK_OF(X509) *ca,
                      int nid_key, int nid_cert, int iter, int mac_iter, int keytype);

PKCS12 *PKCS12_create_ex(const char *pass, const char *name, EVP_PKEY *pkey,
                         X509 *cert, STACK_OF(X509) *ca, int nid_key, int nid_cert,
                         int iter, int mac_iter, int keytype,
                         OSSL_LIB_CTX *ctx, const char *propq);

typedef int PKCS12_create_cb(PKCS12_SAFEBAG *bag, void *cbarg);

PKCS12 *PKCS12_create_ex2(const char *pass, const char *name, EVP_PKEY *pkey,
                          X509 *cert, STACK_OF(X509) *ca, int nid_key, int nid_cert,
                          int iter, int mac_iter, int keytype,
                          OSSL_LIB_CTX *ctx, const char *propq,
                          PKCS12_create_cb *cb, void *cbarg);

Like, four whole flavors of the same vibe. The first two are giving classic vs. modern, and _ex2 is the one with the callback slay. 💅

🦋 DESCRIPTION 🦋

Okay so <pink>PKCS12_create()</pink> creates a PKCS#12 structure. Groundbreaking, I know. 💀

pass is your passphrase — the secret little password thing. name is the friendlyName used for the certificate and key you're supplying. pkey is the private key going into the structure, and cert is its corresponding certificate. And ca — if it's not NULL — is an optional set of extra certificates you can toss into the structure too. Iconic. ✨

nid_key and nid_cert are the encryption algorithms for the key and the certificate respectively. But heads up bestie: the modes GCM, CCM, XTS, and OCB are unsupported. Not those ones. 🙈 iter is the encryption algorithm iteration count, mac_iter is the MAC iteration count, and keytype is the type of key. Slay.

<pink>PKCS12_create_ex()</pink> is literally identical to PKCS12_create() but lets you use a library context ctx and a property query propq to select algorithm implementations. It's giving "more options, same energy."

<pink>PKCS12_create_ex2()</pink> is identical to PKCS12_create_ex() but lets you specify a user defined callback cb of type PKCS12_create_cb, plus an optional argument cbarg that gets passed back to the callback. Very main character energy. ⭐

So the cb, if you specify it, gets called for every safebag added to the PKCS12 structure, and it lets your application do optional processing on the associated safebag. One such use, for example, could be to add attributes to the safebag. Cute, right? 🎀

🌈 NOTES 🌈

The parameters nid_key, nid_cert, iter, mac_iter, and keytype can all be set to zero, and sensible defaults will be used. Set it and forget it, bestie. 🫶

The defaults are: AES password based encryption (PBES2 with PBKDF2 and AES-256-CBC) for private keys and certificates, the PBKDF2 and MAC key derivation iteration count of PKCS12_DEFAULT_ITER (currently 2048), and MAC algorithm HMAC with SHA2-256. The MAC key derivation algorithm used for the outer PKCS#12 structure is PKCS12KDF. That's a lot of acronyms but you got this. 💪

The default MAC iteration count is 1 — yes, one — to retain compatibility with old software that didn't interpret MAC iteration counts. If you don't need that compatibility, set mac_iter to PKCS12_DEFAULT_ITER. Not me judging old software. 😭

keytype adds a flag to the store private key. It's a non-standard extension that's only currently interpreted by MSIE (iykyk). If it's set to zero, the flag is omitted. If it's set to KEY_SIG, the key can be used for signing only. If it's set to KEY_EX, it can be used for signing and encryption. This option was useful for old export grade software that could use signing only keys of arbitrary size but had restrictions on key sizes used for encryption. History class but make it crypto. 📜

If name is NULL and cert contains an alias, then that alias will be used for the corresponding friendlyName in the PKCS12 structure instead. Similarly, if pkey is NULL and cert contains a keyid, that keyid will be used for the corresponding localKeyID in the PKCS12 structure instead of the id calculated from the pkey. Look at it adapting. 🌟

For all certificates in ca, if a certificate contains an alias or keyid, that will be used for the corresponding friendlyName or localKeyID in the PKCS12 structure. Consistency queen.

Either pkey, cert, or both can be NULL to indicate that no key or certificate is required. In previous versions both had to be present or a fatal error is returned. Glow-up behavior, honestly. ✨

nid_key or nid_cert can be set to -1, indicating no encryption should be used. Unencrypted and unbothered.

mac_iter can be set to -1 and the MAC will be omitted entirely. This can be useful when running with the FIPS provider because the PKCS12KDF is not a FIPS approvable algorithm. Important caveat bestie — don't skip that. 🚨

<pink>PKCS12_create()</pink> makes assumptions regarding the encoding of the given pass phrase. See passphrase-encoding(7) for more info. Go read it. I'll wait. 📖

If cb is specified, it should return 1 for success and -1 for a fatal error. A return of 0 is intended to mean "don't add the bag after all." Three returns, three vibes. Got it? 💅

👑 RETURN VALUES 👑

<pink>PKCS12_create()</pink> returns a valid PKCS12 structure, or NULL if an error occurred. That's it. That's the return. No cap. 🔥

🧚 CONFORMING TO 🧚

IETF RFC 7292 (<https://tools.ietf.org/html/rfc7292>). Standards, but make it cute. 🌸

🍓 SEE ALSO 🍓

All the cross-references, bestie. Don't skip the reading list. 📚

💜 HISTORY 💜

PKCS12_create_ex() was added in OpenSSL 3.0. PKCS12_create_ex2() was added in OpenSSL 3.2. The new kids on the block. 🎀

The defaults for encryption algorithms, MAC algorithm, and the MAC key derivation iteration count were changed in OpenSSL 3.0 to more modern standards. Evolution, honestly. 🦋

Copyright 2002-2024 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>.

okay that's the whole thing bestie, every last flag and caveat, no details skipped, we ate and left no crumbs 💅✨ this was OpenSSL 3.5.6, dated 2026-04-07, and that's the PKCS12_CREATE(3ossl) page — mwah 🫶💖
📦 where this page comes from