go-pkcs12

The pkcs12 package provides functionality for handling PKCS#12 (P12/PFX) files.

Primary Use Cases

• Decoding: Extracting DER-encoded P12/PFX files for use with the standard crypto/tls package.
• Encoding: Creating P12/PFX files for compatibility with legacy applications that do not support newer certificate formats.

Important Constraints and Warnings

• Encoding Support: This package supports only DER-encoded PKCS#12 files. It does not support BER encoding because the underlying encoding/asn1 package is limited to DER.
• Security Warning: PKCS#12 uses weak encryption primitives. It SHOULD NOT be used for new applications where modern security standards can be applied.
• Origin: This package is a fork of the frozen golang.org/x/crypto/pkcs12 and is based on the implementation details from RFC 7292.

To use this package in your Go project, use the following import path for both go get and your source code import statements. Note that while the repository is hosted on GitHub, the official import path is different.

Import Path: software.sslmate.com/src/go-pkcs12

import "software.sslmate.com/src/go-pkcs12"

Use DecodeTrustStore to extract certificates from a PKCS#12 file specifically formatted as a Java TrustStore. This function requires that the certificates are marked with the special Java trust anchor OID (2.16.840.1.113894.746875.1.1).

If the password argument is empty, it will attempt to decode either password-less files or files with a literal empty password.

certs, err := pkcs12.DecodeTrustStore(pfxData, password)

Use Decode if you are certain the PKCS#12 file contains exactly one certificate and one private key. If the file contains more than two safe bags (e.g., a CA chain), this function will return an error.

Note: This function is a wrapper around DecodeChain that enforces a strict limit on the number of items found.

privateKey, certificate, err := pkcs12.Decode(pfxData, password)

The ToPEM function converts all "safe bags" in a PFX file to PEM blocks.

Warning: This function is deprecated. It creates invalid PEM blocks because private keys are encoded as raw RSA or EC private keys rather than PKCS#8, despite being labeled "PRIVATE KEY".

Recommended Alternative: Use DecodeChain to extract the keys/certificates, then use the standard encoding/pem package to encode them as desired.

// Deprecated usage
blocks, err := pkcs12.ToPEM(pfxData, password)

Use DecodeChain to extract a private key, a leaf certificate, and a CA certificate chain from a DER-encoded PKCS#12 file. This is the recommended method for most use cases as PKCS#12 files often contain multiple certificates.

Note: The first certificate in the chain is assumed to be the leaf certificate, and subsequent certificates are treated as the CA chain.

privateKey, certificate, caCerts, err := pkcs12.DecodeChain(pfxData, password)

Use EncodeTrustStore to create a PKCS#12 file containing CA certificates marked for use as a Java TrustStore. The certificates' Subjects are used as their Friendly Names (Aliases).

To specify custom Friendly Names for each certificate, use EncodeTrustStoreEntries with a slice of TrustStoreEntry objects.

// Simple trust store
pfxData, err := pkcs12.Modern.EncodeTrustStore(certs, password)

// Custom trust store with specific aliases
entries := []pkcs12.TrustStoreEntry{
    {Cert: cert1, FriendlyName: "alias1"},
    {Cert: cert2, FriendlyName: "alias2"},
}
pfxData, err := pkcs12.Modern.EncodeTrustStoreEntries(entries, password)

Use Encoder.Encode to produce a DER-encoded PKCS#12 file containing one private key, one end-entity certificate, and any number of CA certificates.

It emulates OpenSSL's PKCS12_create behavior: it creates two SafeContents—one encrypted (containing certificates) and one unencrypted (containing the shrouded private key). The LocalKeyId attribute is automatically set to the SHA-1 fingerprint of the end-entity certificate.

// Using the Modern encoder
enc := pkcs12.Modern
pfxData, err := enc.Encode(privateKey, certificate, caCerts, password)

When performing PKCS#12 operations, you may encounter specific error variables to identify why an operation failed. Use errors.Is to check for these sentinel errors:

• ErrDecryption: Indicates a failure to decrypt the input, often due to incorrect padding.
• ErrIncorrectPassword: Indicates that the provided password was incorrect. This is typically detected when the P12/PFX data is signed and the signature verification fails.

import (
	"errors"
	"fmt"
	"sslmate/sslmate/go-pkcs12"
)

// Example error checking
err := pkcs12.Decode("data", "wrong-password")
if errors.Is(err, pkcs12.ErrIncorrectPassword) {
	fmt.Println("Please check your password.")
} else if errors.Is(err, pkcs12.ErrDecryption) {
	fmt.Println("Decryption failed: incorrect padding.")
}

The NotImplementedError type is used to indicate that a specific PKCS#12 feature or input format is not currently supported by the library. It is a string-based error type where the error message is prefixed with pkcs12: .

// Example of how a NotImplementedError might be handled
var err error = pkcs12.NotImplementedError("some unsupported feature")
fmt.Println(err.Error()) // Output: pkcs12: some unsupported feature