PKCS8_ENCRYPT(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💖 PKCS8_ENCRYPT 💖

okay so bestie, welcome to the OpenSSL manual page for PKCS8_ENCRYPT(3ossl) — yes that's the real title, she's fancy. this is the little corner of OpenSSL that handles encrypting and decrypting PKCS8 private keys, and by the end you're gonna be obsessed. no cap. 🔥

✨ NAME ✨

PKCS8_decrypt, PKCS8_decrypt_ex, PKCS8_encrypt, PKCS8_encrypt_ex, PKCS8_set0_pbe, PKCS8_set0_pbe_ex — these are the PKCS8 encrypt/decrypt functions. the whole girl squad, all six of them. 💅

🎀 SYNOPSIS 🎀

#include <openssl/x509.h>

PKCS8_PRIV_KEY_INFO *PKCS8_decrypt(const X509_SIG *p8, const char *pass,
                                   int passlen);
PKCS8_PRIV_KEY_INFO *PKCS8_decrypt_ex(const X509_SIG *p8, const char *pass,
                                      int passlen, OSSL_LIB_CTX *ctx,
                                      const char *propq);
X509_SIG *PKCS8_encrypt(int pbe_nid, const EVP_CIPHER *cipher,
                        const char *pass, int passlen, unsigned char *salt,
                        int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8);
X509_SIG *PKCS8_encrypt_ex(int pbe_nid, const EVP_CIPHER *cipher,
                           const char *pass, int passlen, unsigned char *salt,
                           int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8,
                           OSSL_LIB_CTX *ctx, const char *propq);
X509_SIG *PKCS8_set0_pbe(const char *pass, int passlen,
                         PKCS8_PRIV_KEY_INFO *p8inf, X509_ALGOR *pbe);
X509_SIG *PKCS8_set0_pbe_ex(const char *pass, int passlen,
                            PKCS8_PRIV_KEY_INFO *p8inf, X509_ALGOR *pbe,
                            OSSL_LIB_CTX *ctx);

like, look at them. so many arguments. so much power. 🫶

🌸 DESCRIPTION 🌸

okay so what do these actually DO, you ask? let me tell you, because honestly it's giving cryptography main character energy:

  • PKCS8_encrypt() and PKCS8_encrypt_ex() literally perform encryption of an object p8 using the password pass of length passlen, salt salt of length saltlen and iteration count iter. the resulting X509_SIG contains the encoded algorithm parameters and the encrypted key. so you hand her the key, the password, the salt, the iteration count, and she hands you back a whole X509_SIG. iconic behaviour. ✨
  • PKCS8_decrypt() and PKCS8_decrypt_ex() perform decryption of an X509_SIG in p8 using the password pass of length passlen, along with the algorithm parameters obtained from the p8. she reads the params right off the thing itself, no extra help needed. self-sufficient queen. 👑
  • PKCS8_set0_pbe() and PKCS8_set0_pbe_ex() perform encryption of the p8inf using the password pass of length passlen and parameters pbe. this is the one where you bring your own pbe params instead of letting her pick. very DIY of you. 🎀

and the tea on the _ex() girlies ☕: functions ending in _ex() allow for a library context ctx and property query propq to be used to select algorithm implementations. so if you're being picky about which implementation does the actual work, _ex() is your bestie. fr fr. 💜

🦋 RETURN VALUES 🦋

  • PKCS8_encrypt(), PKCS8_encrypt_ex(), PKCS8_set0_pbe() and PKCS8_set0_pbe_ex() return an encrypted key in a X509_SIG structure, or NULL if an error occurs. 🫶
  • PKCS8_decrypt() and PKCS8_decrypt_ex() return a PKCS8_PRIV_KEY_INFO, or NULL if an error occurs.
⚠️ and like, obviously check for NULL, bestie. NULL means something went wrong. don't just vibe past it. 😭

🌈 CONFORMING TO 🌈

she conforms to IETF RFC 7292 (<https://tools.ietf.org/html/rfc7292>). standards-compliant and gorgeous. 💖

💜 SEE ALSO 💜

crypto(7) — go read it, iykyk. 📖

⭐ HISTORY ⭐

PKCS8_decrypt_ex(), PKCS8_encrypt_ex() and PKCS8_set0_pbe_ex() were added in OpenSSL 3.0. so the _ex girlies are the newer additions to the family — the OGs came first. 🌸

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

so yeah, read the license, don't be that person. 🙈

and that's the whole page, bestie!! 💅✨ this version is from OpenSSL 3.5.0, dated 2026-09-25, and it's the PKCS8_ENCRYPT(3ossl) manual — go forth and encrypt responsibly. mwah. 🎀🦋💖

📦 where this page comes from