PKCS12_NEWPASS(3ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💅 NAME 💅

Okay bestie, so PKCS12_newpass — it's the glow-up function for a PKCS12 structure. It changes the password. That's the whole vibe. Like giving your p12 a whole new lock and key, periodt. ✨

(also hi, this is the OpenSSL manual page PKCS12_NEWPASS(3ossl), welcome to the group chat 🫶)

✨ 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 it, that's the function, main character energy fr.

p12 is a pointer to a PKCS12 structure. oldpass is the existing password and newpass is the new password. Slay, three args, no notes. 💖

Now here's the part where you gotta pay attention, bestie, because encoding is lowkey the whole plot twist: each 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.

In particular — and the docs say "in particular" because this is the actual tea ☕ — this means that passwords in the locale character set (or code page on Windows) must potentially be converted to UTF-8 before use. Yeah. Before. Not after. This may include passwords from local text files, or input from the terminal or command line. Refer to the documentation of UI_OpenSSL(3), for example. iykyk 🌈

🚨 no-password p12? Listen up: if the PKCS#12 structure does not have a password, then you must use the empty string "" for oldpass. Using NULL for oldpass will result in a PKCS12_newpass() failure. So "" is your girl, NULL is not. 💀

And if you feed it the wrong password for oldpass? The function will fail, with a MAC verification error. Periodt. But in rare cases the PKCS12 structure does not contain a MAC: in this case it will usually fail with a decryption padding error. Different error, same heartbreak 😭

🎀 RETURN VALUES 🎀

  • PKCS12_newpass() returns 1 on success.
  • It returns 0 on failure.

Applications can retrieve the most recent error from PKCS12_newpass() with ERR_get_error(). Use it, bestie, don't just stare at the 0 and hope for the best 🙈

🌸 EXAMPLES 🌸

Okay so picture this: this example loads a PKCS#12 file, changes its password and writes out the result to a new file. Iconic. It ate, honestly.

#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;
}

Notice how every single return 1 path that already has a p12 frees it first? That's not a coincidence bestie, that's PKCS12_free(p12) doing its job every single time 💅

💀 BUGS 💀

Not gonna lie to you: the password format is a NULL terminated ASCII string which is converted to Unicode form internally. As a result some passwords cannot be supplied to this function. As in, genuinely cannot. No workaround listed here, it's just like that 😭 Maybe not the vibe you wanted but it's the vibe you're getting.

🔥 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 the whole page bestie, mwah 💖 This little masterpiece is from the OpenSSL docs, version 3.5.6, dated 2026-04-07 — go change some passwords, you've got this 🧚✨

📦 where this page comes from