pkcs8

README

pkcs8

OpenSSL can generate private keys in both "traditional format" and PKCS#8 format. Newer applications are advised to use more secure PKCS#8 format. Go standard crypto package provides a function to parse private key in PKCS#8 format. There is a limitation to this function. It can only handle unencrypted PKCS#8 private keys. To use this function, the user has to save the private key in file without encryption, which is a bad practice to leave private keys unprotected on file systems. In addition, Go standard package lacks the functions to convert RSA/ECDSA private keys into PKCS#8 format.

pkcs8 package fills the gap here. It implements functions to process private keys in PKCS#8 format, as defined in RFC5208 and RFC5958. It can handle both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo format with PKCS#5 (v2.0) algorithms.

Godoc

Installation

Supports Go 1.10+. Release v1.1 is the last release supporting Go 1.9

go get github.com/youmark/pkcs8

dependency

This package depends on golang.org/x/crypto/pbkdf2 and golang.org/x/crypto/scrypt packages. Use the following command to retrieve them

go get golang.org/x/crypto/pbkdf2
go get golang.org/x/crypto/scrypt

Documentation

Overview

Package pkcs8 implements functions to parse and convert private keys in PKCS#8 format, as defined in RFC5208 and RFC5958

Index

• Variables
• func ConvertPrivateKeyToPKCS8(priv interface{}, v ...[]byte) ([]byte, error)
• func EncryptPKCS8(pkcs8Bytes []byte, password []byte, opts *Opts) ([]byte, error)
• func MarshalPrivateKey(priv interface{}, password []byte, opts *Opts) ([]byte, error)
• func ParsePKCS8PrivateKey(der []byte, v ...[]byte) (interface{}, error)
• func ParsePKCS8PrivateKeyECDSA(der []byte, v ...[]byte) (*ecdsa.PrivateKey, error)
• func ParsePKCS8PrivateKeyRSA(der []byte, v ...[]byte) (*rsa.PrivateKey, error)
• func RegisterCipher(oid asn1.ObjectIdentifier, cipher func() Cipher)
• func RegisterKDF(oid asn1.ObjectIdentifier, params func() KDFParameters)
• type Cipher
• type KDFOpts
• type KDFParameters
  • func DecryptPKCS8(encryptedPkcs8 []byte, password []byte) ([]byte, KDFParameters, error)
  • func ParsePrivateKey(der []byte, password []byte) (interface{}, KDFParameters, error)
• type Opts
• type PBKDF2Opts
  • func (p PBKDF2Opts) DeriveKey(password, salt []byte, size int) (key []byte, params KDFParameters, err error)
  • func (p PBKDF2Opts) GetSaltSize() int
  • func (p PBKDF2Opts) OID() asn1.ObjectIdentifier
• type ScryptOpts
  • func (p ScryptOpts) DeriveKey(password, salt []byte, size int) (key []byte, params KDFParameters, err error)
  • func (p ScryptOpts) GetSaltSize() int
  • func (p ScryptOpts) OID() asn1.ObjectIdentifier

Variables

var AES128CBC = cipherWithBlock{
	// contains filtered or unexported fields
}

AES128CBC is the 128-bit key AES cipher in CBC mode.

var AES128GCM = cipherWithBlock{
	// contains filtered or unexported fields
}

AES128GCM is the 128-bit key AES cipher in GCM mode.

var AES192CBC = cipherWithBlock{
	// contains filtered or unexported fields
}

AES192CBC is the 192-bit key AES cipher in CBC mode.

var AES192GCM = cipherWithBlock{
	// contains filtered or unexported fields
}

AES192GCM is the 912-bit key AES cipher in GCM mode.

var AES256CBC = cipherWithBlock{
	// contains filtered or unexported fields
}

AES256CBC is the 256-bit key AES cipher in CBC mode.

var AES256GCM = cipherWithBlock{
	// contains filtered or unexported fields
}

AES256GCM is the 256-bit key AES cipher in GCM mode.

var DefaultOpts = &Opts{
	Cipher: AES256GCM,
	KDFOpts: PBKDF2Opts{
		SaltSize:       16,
		IterationCount: 10240,
		HMACHash:       crypto.SHA256,
	},
}

var TripleDESCBC = cipherWithBlock{
	// contains filtered or unexported fields
}

TripleDESCBC is the 168-bit key 3DES cipher in CBC mode.

Functions

func ConvertPrivateKeyToPKCS8

func ConvertPrivateKeyToPKCS8(priv interface{}, v ...[]byte) ([]byte, error)

ConvertPrivateKeyToPKCS8 converts the private key into PKCS#8 format. To encrypt the private key, the password of []byte type should be provided as the second parameter.

The only supported key types are RSA and ECDSA (*rsa.PrivateKey or *ecdsa.PrivateKey for priv)

func EncryptPKCS8

func EncryptPKCS8(pkcs8Bytes []byte, password []byte, opts *Opts) ([]byte, error)

func MarshalPrivateKey

func MarshalPrivateKey(priv interface{}, password []byte, opts *Opts) ([]byte, error)

MarshalPrivateKey encodes a private key into DER-encoded PKCS#8 with the given options. Password can be nil.

func ParsePKCS8PrivateKey

func ParsePKCS8PrivateKey(der []byte, v ...[]byte) (interface{}, error)

ParsePKCS8PrivateKey parses encrypted/unencrypted private keys in PKCS#8 format. To parse encrypted private keys, a password of []byte type should be provided to the function as the second parameter.

func ParsePKCS8PrivateKeyECDSA

func ParsePKCS8PrivateKeyECDSA(der []byte, v ...[]byte) (*ecdsa.PrivateKey, error)

ParsePKCS8PrivateKeyECDSA parses encrypted/unencrypted private keys in PKCS#8 format. To parse encrypted private keys, a password of []byte type should be provided to the function as the second parameter.

func ParsePKCS8PrivateKeyRSA

func ParsePKCS8PrivateKeyRSA(der []byte, v ...[]byte) (*rsa.PrivateKey, error)

ParsePKCS8PrivateKeyRSA parses encrypted/unencrypted private keys in PKCS#8 format. To parse encrypted private keys, a password of []byte type should be provided to the function as the second parameter.

func RegisterCipher

func RegisterCipher(oid asn1.ObjectIdentifier, cipher func() Cipher)

RegisterCipher registers a function that returns a new instance of the given cipher. This allows the library to support client-provided ciphers.

func RegisterKDF

func RegisterKDF(oid asn1.ObjectIdentifier, params func() KDFParameters)

RegisterKDF registers a function that returns a new instance of the given KDF parameters. This allows the library to support client-provided KDFs.

Types

type Cipher

type Cipher interface {
	// IVSize returns the IV size of the cipher, in bytes.
	IVSize() int
	// KeySize returns the key size of the cipher, in bytes.
	KeySize() int
	// Encrypt encrypts the key material.
	Encrypt(key, iv, plaintext []byte) ([]byte, error)
	// Decrypt decrypts the key material.
	Decrypt(key, iv, ciphertext []byte) ([]byte, error)
	// OID returns the OID of the cipher specified.
	OID() asn1.ObjectIdentifier
}

Cipher represents a cipher for encrypting the key material.

type KDFOpts

type KDFOpts interface {
	// DeriveKey derives a key of size bytes from the given password and salt.
	// It returns the key and the ASN.1-encodable parameters used.
	DeriveKey(password, salt []byte, size int) (key []byte, params KDFParameters, err error)
	// GetSaltSize returns the salt size specified.
	GetSaltSize() int
	// OID returns the OID of the KDF specified.
	OID() asn1.ObjectIdentifier
}

KDFOpts contains options for a key derivation function. An implementation of this interface must be specified when encrypting a PKCS#8 key.

type KDFParameters

type KDFParameters interface {
	// DeriveKey derives a key of size bytes from the given password.
	// It uses the salt from the decoded parameters.
	DeriveKey(password []byte, size int) (key []byte, err error)
}

KDFParameters contains parameters (salt, etc.) for a key deriviation function. It must be a ASN.1-decodable structure. An implementation of this interface is created when decoding an encrypted PKCS#8 key.

func DecryptPKCS8

func DecryptPKCS8(encryptedPkcs8 []byte, password []byte) ([]byte, KDFParameters, error)

func ParsePrivateKey

func ParsePrivateKey(der []byte, password []byte) (interface{}, KDFParameters, error)

ParsePrivateKey parses a DER-encoded PKCS#8 private key. Password can be nil. This is equivalent to ParsePKCS8PrivateKey.

type Opts

type Opts struct {
	Cipher  Cipher
	KDFOpts KDFOpts
}

Opts contains options for encrypting a PKCS#8 key.

type PBKDF2Opts

type PBKDF2Opts struct {
	SaltSize       int
	IterationCount int
	HMACHash       crypto.Hash
}

PBKDF2Opts contains options for the PBKDF2 key derivation function.

func (PBKDF2Opts) DeriveKey

func (p PBKDF2Opts) DeriveKey(password, salt []byte, size int) (
	key []byte, params KDFParameters, err error)

func (PBKDF2Opts) GetSaltSize

func (p PBKDF2Opts) GetSaltSize() int

func (PBKDF2Opts) OID

func (p PBKDF2Opts) OID() asn1.ObjectIdentifier

type ScryptOpts

type ScryptOpts struct {
	SaltSize                 int
	CostParameter            int
	BlockSize                int
	ParallelizationParameter int
}

ScryptOpts contains options for the scrypt key derivation function.

func (ScryptOpts) DeriveKey

func (p ScryptOpts) DeriveKey(password, salt []byte, size int) (
	key []byte, params KDFParameters, err error)

func (ScryptOpts) GetSaltSize

func (p ScryptOpts) GetSaltSize() int

func (ScryptOpts) OID

func (p ScryptOpts) OID() asn1.ObjectIdentifier