pkcs12

README

package pkcs12

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

Package pkcs12 implements some of PKCS#12 (also known as P12 or PFX). It is intended for decoding DER-encoded P12/PFX files for use with the crypto/tls package, and for encoding P12/PFX files for use by legacy applications which do not support newer formats. Since PKCS#12 uses weak encryption primitives, it SHOULD NOT be used for new applications.

Note that only DER-encoded PKCS#12 files are supported, even though PKCS#12 allows BER encoding. This is becuase encoding/asn1 only supports DER.

This package is forked from golang.org/x/crypto/pkcs12, which is frozen. The implementation is distilled from https://tools.ietf.org/html/rfc7292 and referenced documents.

This repository holds supplementary Go cryptography libraries.

Import Path

Note that although the source code and issue tracker for this package are hosted on GitHub, the import path is:

software.sslmate.com/src/go-pkcs12 

Please be sure to use this path when you go get and import this package.

Download/Install

The easiest way to install is to run go get -u software.sslmate.com/src/go-pkcs12. You can also manually git clone the repository to $GOPATH/src/software.sslmate.com/src/go-pkcs12.

Report Issues / Send Patches

Open an issue or PR at https://github.com/SSLMate/go-pkcs12

Documentation

Overview

Package pkcs12 implements some of PKCS#12 (also known as P12 or PFX). It is intended for decoding DER-encoded P12/PFX files for use with the crypto/tls package, and for encoding P12/PFX files for use by legacy applications which do not support newer formats. Since PKCS#12 uses weak encryption primitives, it SHOULD NOT be used for new applications.

Note that only DER-encoded PKCS#12 files are supported, even though PKCS#12 allows BER encoding. This is becuase encoding/asn1 only supports DER.

This package is forked from golang.org/x/crypto/pkcs12, which is frozen. The implementation is distilled from https://tools.ietf.org/html/rfc7292 and referenced documents.

Index

• Constants
• Variables
• func Decode(pfxData []byte, password string) (privateKey interface{}, certificate *x509.Certificate, err error)
• func DecodeChain(pfxData []byte, password string) (privateKey interface{}, certificate *x509.Certificate, ...)
• func DecodeTrustStore(pfxData []byte, password string) (certs []*x509.Certificate, err error)
• func Encode(rand io.Reader, privateKey interface{}, certificate *x509.Certificate, ...) (pfxData []byte, err error)
• func EncodeTrustStore(rand io.Reader, certs []*x509.Certificate, password string) (pfxData []byte, err error)
• func ToPEM(pfxData []byte, password string) ([]*pem.Block, error)
• type NotImplementedError
  • func (e NotImplementedError) Error() string

Examples

• ToPEM

Constants

const DefaultPassword = "changeit"

DefaultPassword is the string "changeit", a commonly-used password for PKCS#12 files. Due to the weak encryption used by PKCS#12, it is RECOMMENDED that you use DefaultPassword when encoding PKCS#12 files, and protect the PKCS#12 files using other means.

Variables

var (
	// ErrDecryption represents a failure to decrypt the input.
	ErrDecryption = errors.New("pkcs12: decryption error, incorrect padding")

	// ErrIncorrectPassword is returned when an incorrect password is detected.
	// Usually, P12/PFX data is signed to be able to verify the password.
	ErrIncorrectPassword = errors.New("pkcs12: decryption password incorrect")
)

Functions

func Decode

func Decode(pfxData []byte, password string) (privateKey interface{}, certificate *x509.Certificate, err error)

Decode extracts a certificate and private key from pfxData, which must be a DER-encoded PKCS#12 file. This function assumes that there is only one certificate and only one private key in the pfxData. Since PKCS#12 files often contain more than one certificate, you probably want to use DecodeChain instead.

func DecodeChain

func DecodeChain(pfxData []byte, password string) (privateKey interface{}, certificate *x509.Certificate, caCerts []*x509.Certificate, err error)

DecodeChain extracts a certificate, a CA certificate chain, and private key from pfxData, which must be a DER-encoded PKCS#12 file. This function assumes that there is at least one certificate and only one private key in the pfxData. The first certificate is assumed to be the leaf certificate, and subsequent certificates, if any, are assumed to comprise the CA certificate chain.

func DecodeTrustStore

func DecodeTrustStore(pfxData []byte, password string) (certs []*x509.Certificate, err error)

DecodeTrustStore extracts the certificates from pfxData, which must be a DER-encoded PKCS#12 file containing exclusively certificates with attribute 2.16.840.1.113894.746875.1.1, which is used by Java to designate a trust anchor.

func Encode

func Encode(rand io.Reader, privateKey interface{}, certificate *x509.Certificate, caCerts []*x509.Certificate, password string) (pfxData []byte, err error)

Encode produces pfxData containing one private key (privateKey), an end-entity certificate (certificate), and any number of CA certificates (caCerts).

The private key is encrypted with the provided password, but due to the weak encryption primitives used by PKCS#12, it is RECOMMENDED that you specify a hard-coded password (such as pkcs12.DefaultPassword) and protect the resulting pfxData using other means.

The rand argument is used to provide entropy for the encryption, and can be set to rand.Reader from the crypto/rand package.

Encode emulates the behavior of OpenSSL's PKCS12_create: it creates two SafeContents: one that's encrypted with RC2 and contains the certificates, and another that is unencrypted and contains the private key shrouded with 3DES The private key bag and the end-entity certificate bag have the LocalKeyId attribute set to the SHA-1 fingerprint of the end-entity certificate.

func EncodeTrustStore

func EncodeTrustStore(rand io.Reader, certs []*x509.Certificate, password string) (pfxData []byte, err error)

EncodeTrustStore produces pfxData containing any number of CA certificates (certs) to be trusted. The certificates will be marked with a special OID that allow it to be used as a Java TrustStore in Java 1.8 and newer.

Due to the weak encryption primitives used by PKCS#12, it is RECOMMENDED that you specify a hard-coded password (such as pkcs12.DefaultPassword) and protect the resulting pfxData using other means.

The rand argument is used to provide entropy for the encryption, and can be set to rand.Reader from the crypto/rand package.

EncodeTrustStore creates a single SafeContents that's encrypted with RC2 and contains the certificates.

func ToPEM

func ToPEM(pfxData []byte, password string) ([]*pem.Block, error)

ToPEM converts all "safe bags" contained in pfxData to PEM blocks. DO NOT USE THIS FUNCTION. ToPEM creates invalid PEM blocks; private keys are encoded as raw RSA or EC private keys rather than PKCS#8 despite being labeled "PRIVATE KEY". To decode a PKCS#12 file, use DecodeChain instead, and use the encoding/pem package to convert to PEM if necessary.

Example

p12, _ := base64.StdEncoding.DecodeString(`MIIJzgIBAzCCCZQGCS ... CA+gwggPk==`)

blocks, err := ToPEM(p12, "password")
if err != nil {
	panic(err)
}

var pemData []byte
for _, b := range blocks {
	pemData = append(pemData, pem.EncodeToMemory(b)...)
}

// then use PEM data for tls to construct tls certificate:
cert, err := tls.X509KeyPair(pemData, pemData)
if err != nil {
	panic(err)
}

config := &tls.Config{
	Certificates: []tls.Certificate{cert},
}

_ = config

Types

type NotImplementedError

type NotImplementedError string

NotImplementedError indicates that the input is not currently supported.

func (NotImplementedError) Error

func (e NotImplementedError) Error() string