pemutil

Documentation

Overview

Package pemutil implements utilities to parse keys and certificates. It also includes a method to serialize keys, X.509 certificates and certificate requests to PEM.

Index

• Constants
• Variables
• func BundleCertificate(bundlePEM []byte, certsPEM ...[]byte) ([]byte, bool, error)
• func DecryptPEMBlock(block *pem.Block, password []byte) ([]byte, error)
• func DecryptPKCS8PrivateKey(data, password []byte) ([]byte, error)
• func EncryptPKCS8PrivateKey(rand io.Reader, data, password []byte, alg x509.PEMCipher) (*pem.Block, error)
• func Parse(b []byte, opts ...Options) (interface{}, error)
• func ParseCertificate(pemData []byte) (*x509.Certificate, error)
• func ParseCertificateBundle(pemData []byte) ([]*x509.Certificate, error)
• func ParseCertificateRequest(pemData []byte) (*x509.CertificateRequest, error)
• func ParseCosignPrivateKey(data, password []byte) (crypto.PrivateKey, error)
• func ParseDER(b []byte) (interface{}, error)
• func ParseKey(b []byte, opts ...Options) (interface{}, error)
• func ParseOpenSSHPrivateKey(pemBytes []byte, opts ...Options) (crypto.PrivateKey, error)
• func ParseSSH(b []byte) (interface{}, error)
• func Read(filename string, opts ...Options) (interface{}, error)
• func ReadCertificate(filename string, opts ...Options) (*x509.Certificate, error)
• func ReadCertificateBundle(filename string) ([]*x509.Certificate, error)
• func ReadCertificateRequest(filename string) (*x509.CertificateRequest, error)
• func Serialize(in interface{}, opts ...Options) (*pem.Block, error)
• func SerializeOpenSSHPrivateKey(key crypto.PrivateKey, opts ...Options) (*pem.Block, error)
• func UnbundleCertificate(bundlePEM []byte, certsPEM ...[]byte) ([]byte, bool, error)
• type FileWriter
• type InvalidPEMError
  • func (e *InvalidPEMError) Error() string
  • func (e *InvalidPEMError) Unwrap() error
• type Options
  • func ToFile(name string, perm os.FileMode) Options
  • func WithComment(comment string) Options
  • func WithFilename(name string) Options
  • func WithFirstBlock() Options
  • func WithOpenSSH(v bool) Options
  • func WithPKCS8(v bool) Options
  • func WithPassword(pass []byte) Options
  • func WithPasswordFile(filename string) Options
  • func WithPasswordPrompt(prompt string, fn PasswordPrompter) Options
• type PEMType
  • func (pt PEMType) String() string
• type PasswordPrompter

Constants

const (
	// PEMTypeUndefined undefined
	PEMTypeUndefined = iota
	// PEMTypeCertificate CERTIFICATE
	PEMTypeCertificate
	// PEMTypeCertificateRequest CERTIFICATE REQUEST
	PEMTypeCertificateRequest
)

const PBKDF2Iterations = 600000

PBKDF2Iterations is the default number of iterations for PBKDF2.

600k is the current OWASP recommendation (Dec 2022) https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2

Nist recommends at least 10k (800-63B), 1Password increased in 2023 the number of iterations from 100k to 650k.

const PBKDF2SaltSize = 16

PBKDF2SaltSize is the default size of the salt for PBKDF2, 128-bit salt.

Variables

var DefaultEncCipher = x509.PEMCipherAES256

DefaultEncCipher is the default algorithm used when encrypting sensitive data in the PEM format.

var PEMBlockHeader = []byte("-----BEGIN ")

PEMBlockHeader is the expected header for any PEM formatted block.

Functions

func BundleCertificate

func BundleCertificate(bundlePEM []byte, certsPEM ...[]byte) ([]byte, bool, error)

BundleCertificate adds PEM-encoded certificates to a PEM-encoded certificate bundle if not already in the bundle.

func DecryptPEMBlock

func DecryptPEMBlock(block *pem.Block, password []byte) ([]byte, error)

DecryptPEMBlock takes a password encrypted PEM block and the password used to encrypt it and returns a slice of decrypted DER encoded bytes.

If the PEM blocks has the Proc-Type header set to "4,ENCRYPTED" it uses x509.DecryptPEMBlock to decrypt the block. If not it tries to decrypt the block using AES-128-CBC, AES-192-CBC, AES-256-CBC, DES, or 3DES using the key derived using PBKDF2 over the given password.

func DecryptPKCS8PrivateKey

func DecryptPKCS8PrivateKey(data, password []byte) ([]byte, error)

DecryptPKCS8PrivateKey takes a password encrypted private key using the PKCS#8 encoding and returns the decrypted data in PKCS#8 form. If an incorrect password is detected an x509.IncorrectPasswordError is returned. Because of deficiencies in the format, it's not always possible to detect an incorrect password. In these cases no error will be returned but the decrypted DER bytes will be random noise.

It supports AES-128-CBC, AES-192-CBC, AES-256-CBC, DES, or 3DES encrypted data using the key derived with PBKDF2 over the given password.

func EncryptPKCS8PrivateKey

func EncryptPKCS8PrivateKey(rand io.Reader, data, password []byte, alg x509.PEMCipher) (*pem.Block, error)

EncryptPKCS8PrivateKey returns a PEM block holding the given PKCS#8 encroded private key, encrypted with the specified algorithm and a PBKDF2 derived key from the given password.

func Parse

func Parse(b []byte, opts ...Options) (interface{}, error)

Parse returns the key or certificate PEM-encoded in the given bytes.

func ParseCertificate

func ParseCertificate(pemData []byte) (*x509.Certificate, error)

ParseCertificate extracts the first certificate from the given pem.

func ParseCertificateBundle

func ParseCertificateBundle(pemData []byte) ([]*x509.Certificate, error)

ParseCertificateBundle extracts all the certificates in the given data.

func ParseCertificateRequest

func ParseCertificateRequest(pemData []byte) (*x509.CertificateRequest, error)

ParseCertificateRequest extracts the first certificate from the given pem.

func ParseCosignPrivateKey

func ParseCosignPrivateKey(data, password []byte) (crypto.PrivateKey, error)

ParseCosignPrivateKey returns the private key encoded using cosign envelope. If an incorrect password is detected an x509.IncorrectPasswordError is returned.

Cosign keys are encrypted under a password using scrypt as a KDF and nacl/secretbox for encryption.

func ParseDER

func ParseDER(b []byte) (interface{}, error)

ParseDER parses the given DER-encoded bytes and results the public or private key encoded.

func ParseKey

func ParseKey(b []byte, opts ...Options) (interface{}, error)

ParseKey returns the key or the public key of a certificate or certificate signing request in the given PEM-encoded bytes.

func ParseOpenSSHPrivateKey

func ParseOpenSSHPrivateKey(pemBytes []byte, opts ...Options) (crypto.PrivateKey, error)

ParseOpenSSHPrivateKey parses a private key in OpenSSH PEM format.

Implemented based on the documentation at https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key

This method is based on the implementation at https://github.com/golang/crypto/blob/master/ssh/keys.go

func ParseSSH

func ParseSSH(b []byte) (interface{}, error)

ParseSSH parses parses a public key from an authorized_keys file used in OpenSSH according to the sshd(8) manual page.

func Read

func Read(filename string, opts ...Options) (interface{}, error)

Read returns the key or certificate encoded in the given PEM file. If the file is encrypted it will ask for a password and it will try to decrypt it.

Supported keys algorithms are RSA and EC. Supported standards for private keys are PKCS#1, PKCS#8, RFC5915 for EC, and base64-encoded DER for certificates and public keys.

func ReadCertificate

func ReadCertificate(filename string, opts ...Options) (*x509.Certificate, error)

ReadCertificate returns a *x509.Certificate from the given filename. It supports certificates formats PEM and DER.

func ReadCertificateBundle

func ReadCertificateBundle(filename string) ([]*x509.Certificate, error)

ReadCertificateBundle returns a list of *x509.Certificate from the given filename. It supports certificates formats PEM and DER. If a DER-formatted file is given only one certificate will be returned.

func ReadCertificateRequest

func ReadCertificateRequest(filename string) (*x509.CertificateRequest, error)

ReadCertificateRequest returns a *x509.CertificateRequest from the given filename. It supports certificates formats PEM and DER.

func Serialize

func Serialize(in interface{}, opts ...Options) (*pem.Block, error)

Serialize will serialize the input to a PEM formatted block and apply modifiers.

func SerializeOpenSSHPrivateKey

func SerializeOpenSSHPrivateKey(key crypto.PrivateKey, opts ...Options) (*pem.Block, error)

SerializeOpenSSHPrivateKey serialize a private key in the OpenSSH PEM format.

func UnbundleCertificate

func UnbundleCertificate(bundlePEM []byte, certsPEM ...[]byte) ([]byte, bool, error)

UnbundleCertificate removes PEM-encoded certificates from a PEM-encoded certificate bundle.

Types

type FileWriter

type FileWriter func(filename string, data []byte, perm os.FileMode) error

FileWriter defines the function signature for the WriteFile callback.

var WriteFile FileWriter = utils.WriteFile

WriteFile is a method used to write a file, by default it uses a wrapper over ioutil.WriteFile, but it can be set to a custom method, that for example can check if a file exists and prompts the user if it should be overwritten.

type InvalidPEMError

type InvalidPEMError struct {
	Type    PEMType
	File    string
	Message string
	Err     error
}

InvalidPEMError represents an error that occurs when parsing a file with PEM encoded data.

func (*InvalidPEMError) Error

func (e *InvalidPEMError) Error() string

func (*InvalidPEMError) Unwrap

func (e *InvalidPEMError) Unwrap() error

type Options

type Options func(o *context) error

Options is the type to add attributes to the context.

func ToFile

func ToFile(name string, perm os.FileMode) Options

ToFile is a method that adds the given filename and permissions to the context. It is used in the Serialize to store PEM in disk.

func WithComment

func WithComment(comment string) Options

WithComment is an option used in the Serialize method to add a comment in the OpenSSH private keys. WithOpenSSH must be set to true too.

func WithFilename

func WithFilename(name string) Options

WithFilename is a method that adds the given filename to the context.

func WithFirstBlock

func WithFirstBlock() Options

WithFirstBlock will avoid failing if a PEM contains more than one block or certificate and it will only look at the first.

func WithOpenSSH

func WithOpenSSH(v bool) Options

WithOpenSSH is an option used in the Serialize method to use OpenSSH encoding form on the private keys. With v set to false default form will be used.

func WithPKCS8

func WithPKCS8(v bool) Options

WithPKCS8 with v set to true returns an option used in the Serialize method to use the PKCS#8 encoding form on the private keys. With v set to false default form will be used.

func WithPassword

func WithPassword(pass []byte) Options

WithPassword is a method that adds the given password to the context.

func WithPasswordFile

func WithPasswordFile(filename string) Options

WithPasswordFile is a method that adds the password in a file to the context.

func WithPasswordPrompt

func WithPasswordPrompt(prompt string, fn PasswordPrompter) Options

WithPasswordPrompt ask the user for a password and adds it to the context.

type PEMType

type PEMType int

PEMType represents a PEM block type. (e.g., CERTIFICATE, CERTIFICATE REQUEST, etc.)

func (PEMType) String

func (pt PEMType) String() string

type PasswordPrompter

type PasswordPrompter func(s string) ([]byte, error)

PasswordPrompter defines the function signature for the PromptPassword callback.

var PromptPassword PasswordPrompter

PromptPassword is a method used to prompt for a password to decode encrypted keys. If this method is not defined and the key or password are not passed, the parse of the key will fail.