PKCS12_NEWPASS(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💖 PKCS12_NEWPASS 💖

okay bestie, pull up a chair, because we're doing PKCS12_newpass from the OpenSSL manual — PKCS12_NEWPASS(3SSL) for the formal girlies. it's literally the glow-up function for your PKCS#12 file's password. let's get into it ✨

🎀 NAME 🎀

PKCS12_newpass — change the password of a PKCS12 structure

like, the password. of the PKCS12. she's evolving 💅

🌸 SYNOPSIS 🌸

#include <openssl/pkcs12.h>

int PKCS12_newpass(PKCS12 *p12, const char *oldpass, const char *newpass);

✨ DESCRIPTION ✨

so PKCS12_newpass() changes the password of a PKCS12 structure. that's the whole job. that's the assignment. and she ate 🫶

p12 is a pointer to a PKCS12 structure. oldpass is the existing password and newpass is the new password. iconic, no notes.

now here's the part where you gotta pay attention because this is the encoding lore and it matters: every single one of oldpass and newpass is, independently, interpreted as a string in the UTF-8 encoding. if it is not valid UTF-8, it is assumed to be ISO8859-1 instead. independently, ok? they each get their own vibe check. one can be UTF-8 and the other not. slay.

in particular — and the manpage is being very real about this — this means that passwords in the locale character set (or code page on Windows) must potentially be converted to UTF-8 before use. and that may include passwords from local text files, or input from the terminal or command line. so yeah, the encoding journey is real. refer to the documentation of UI_OpenSSL(3), for example. 🌈

okay now, the no-password situation, because this trips people up every time:

  • if the PKCS#12 structure does not have a password, then you must use the empty string "" for oldpass. not NULL. do not send NULL.
  • using NULL for oldpass will result in a PKCS12_newpass() failure. 💀

and if the wrong password is used for oldpass, then the function will fail with a MAC verification error. in rare cases the PKCS12 structure does not contain a MAC: in this case it will usually fail with a decryption padding error. either way bestie, she's not going through. it's giving rejection, respectfully. 😭

💜 RETURN VALUES 💜

PKCS12_newpass() returns 1 on success or 0 on failure. yep, classic. applications can retrieve the most recent error from PKCS12_newpass() with ERR_get_error(). go get your receipts, king. 👑

🦋 EXAMPLES 🦋

okay bestie here's the full demo — this example loads a PKCS#12 file, changes its password and writes out the result to a new file. literal main character energy, saving you from writing it yourself:

#include <stdio.h>
#include <stdlib.h>
#include <openssl/pem.h>
#include <openssl/err.h>
#include <openssl/pkcs12.h>

int main(int argc, char **argv)
{
    FILE *fp;
    PKCS12 *p12;

    if (argc != 5) {
        fprintf(stderr, "Usage: pkread p12file password newpass opfile\n");
        return 1;
    }
    if ((fp = fopen(argv[1], "rb")) == NULL) {
        fprintf(stderr, "Error opening file %s\n", argv[1]);
        return 1;
    }
    p12 = d2i_PKCS12_fp(fp, NULL);
    fclose(fp);
    if (p12 == NULL) {
        fprintf(stderr, "Error reading PKCS#12 file\n");
        ERR_print_errors_fp(stderr);
        return 1;
    }
    if (PKCS12_newpass(p12, argv[2], argv[3]) == 0) {
        fprintf(stderr, "Error changing password\n");
        ERR_print_errors_fp(stderr);
        PKCS12_free(p12);
        return 1;
    }
    if ((fp = fopen(argv[4], "wb")) == NULL) {
        fprintf(stderr, "Error opening file %s\n", argv[4]);
        PKCS12_free(p12);
        return 1;
    }
    i2d_PKCS12_fp(fp, p12);
    PKCS12_free(p12);
    fclose(fp);
    return 0;
}

🙈 BUGS 🙈

ngl, there's a catch and we're keeping it real about it: the password format is a <b>NULL terminated ASCII string</b> which is converted to Unicode form internally. as a result some passwords cannot be supplied to this function. so like, not every password gets to come to the party. 💅

🌟 SEE ALSO 🌟

Copyright 2016-2018 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>.

and that's a wrap, bestie 🫶 this whole thing came to you from OpenSSL version 4.0.3, dated 2026-09-29, and it's the PKCS12_NEWPASS(3SSL) page — go change those passwords responsibly, and don't you dare pass NULL. mwah 💋✨

📦 where this page comes from