keys

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 17, 2023 License: BSD-3-Clause Imports: 16 Imported by: 0

Documentation

Overview

Package keys provides support for working with an extensible set of cryptographic keys. Parsing and marshaling of different key formats is supported, including the ability to use external agents to host private keys and perform key signing operations.

Extensibility is provided via a registration mechanism (keys.Registrar) that allows for parsing operations to be associated with PEM block types and non-PEM, plain text, data. Marshaling operations are associated with types and a common API interface can also be registered for specific types.

A specific PEM type, keys.PrivateKeyPEMType, is used to support 'indirect' private keys where an indirect key is one whose PEM encoding refers to an external file or agent. This allows for private keys to be hosted by ssh agents for example, or indeed other services such as AWS' secrets service. Other than support for ssh agents, other signing services are not implemented in this package in order to reduce dependencies. Multiple indirections are via a PEM header that is used to identify a specific parser to invoke.

Index

Constants

View Source 
const (
	// IndirectionPrivateKeyPEMType is the PEM type used for the 'indirect'
	// PEM blocks intepreted by registrar.ParsePrivateKey.
	IndirectionPrivateKeyPEMType = "VANADIUM INDIRECT PRIVATE KEY"
	// IndirectionTypePEMHeader is a PEM header used to match an 'indirect'
	// PEM block to a particular parser.
	IndirectionTypePEMHeader = "Vanadium-Indirection-Type"
)

Variables

This section is empty.

Functions

func DecryptPEMBlock 

func DecryptPEMBlock(block *pem.Block, passphrase []byte) (*pem.Block, crypto.PrivateKey, error)

DecryptPEMBlock decrypts an encrypted PEM block. Deprecated: use PKCS8 encryption instead.

func DecryptPKCS8Block 

func DecryptPKCS8Block(block *pem.Block, passphrase []byte) (*pem.Block, crypto.PrivateKey, error)

DecryptPKCS8Block decrypts a private key encrypted using PKCS8. The block's PEM type must be "ENCRYPTED PRIVATE KEY".

func IndirectMatcherFunc 

func IndirectMatcherFunc(indirectionType string) func(b *pem.Block) bool

IndirectMatcherFunc returns a function that can be used to match an 'indirect' PEM block's IndirectionTypePEMHeader.

func MarshalFuncForIndirection 

func MarshalFuncForIndirection(indirectionType string) func(contents []byte) ([]byte, error)

MarshalFuncForIndirection returns a function that can be used to marshal its contents to an 'indirect' PEM block as understood by registrar.ParsePrivateKey for the specified indirectionType. The resulting PEM block will be matched by the function returned IndirectMatcherFunc for the same value of indirectionType.

func MarshalPKCS8PrivateKey 

func MarshalPKCS8PrivateKey(key crypto.PrivateKey, passphrase []byte) ([]byte, error)

MarshalPKCS8PrivateKey uses x509.MarshalPKCS8PrivateKey to marshal the key to PEM block type of 'PRIVATE KEY'. If a passphrase is provided the key will be encrypted using PKCS8 rather than PEM..

func MarshalPKIXPublicKey 

func MarshalPKIXPublicKey(key crypto.PublicKey) ([]byte, error)

MarshalPKIXPublicKey uses MarshalPKIXPublicKey to marshal the key to PEM block of type 'PUBLIC 'KEY'.

func MustRegister 

func MustRegister(r *Registrar)

MustRegister is like Register but panics on error.

func NewPrivateKeyForAlgo 

func NewPrivateKeyForAlgo(algo CryptoAlgo) (crypto.PrivateKey, error)

NewPrivateKeyForAlgo creates a new private key for the requested algorithm.

func ParseECPrivateKey 

func ParseECPrivateKey(block *pem.Block) (crypto.PrivateKey, error)

ParseECPrivateKey calls x509.ParseECPrivateKey with block.Bytes.

func ParsePKCS8PrivateKey 

func ParsePKCS8PrivateKey(block *pem.Block) (crypto.PrivateKey, error)

ParsePKCS8PrivateKey calls x509.ParsePKCS8PrivateKey with block.Bytes.

func ParsePKIXPublicKey 

func ParsePKIXPublicKey(block *pem.Block) (crypto.PublicKey, error)

ParsePKIXPublicKey calls x509.ParsePKIXPublicKey with block.Bytes.

func Register 

func Register(r *Registrar) error

Register registers the required functions for handling the Vanadium built in key types and commonly used formats. These are currently the crypto/ecsda, crypto/ed25519 and crypto/rsa algorithms with parsers provided for variety of PEM block types. PEM and PKCS8 decryption are supported but PCKS8 is is used for encryption.

func ZeroPassphrase 

func ZeroPassphrase(pass []byte)

ZeroPassphrase overwrites the passphrase.

Types

type API 

type API interface {
	Signer(ctx context.Context, key crypto.PrivateKey) (security.Signer, error)
	PublicKey(key interface{}) (security.PublicKey, error)
	CryptoPublicKey(key interface{}) (crypto.PublicKey, error)
}

API represents a common set of operations that can be implemented for specific key types.

type CryptoAlgo 

type CryptoAlgo int

CryptoAlgo represents the supported cryptographic algorithms. 

const (
	UnsupportedAlgoType CryptoAlgo = iota
	ECDSA256
	ECDSA384
	ECDSA521
	ED25519
	RSA2048
	RSA4096
)

Supported key types.

func (CryptoAlgo) String 

func (algo CryptoAlgo) String() string

type DecryptFunc 

type DecryptFunc func(block *pem.Block, passphrase []byte) (*pem.Block, crypto.PrivateKey, error)

DecryptFunc decrypts a pem block using the supplied passphrase.

type ErrBadPassphrase 

type ErrBadPassphrase struct{}

ErrBadPassphrase is returned when the supplied passphrase is unable to decrypt the key.

func (*ErrBadPassphrase) Error 

func (*ErrBadPassphrase) Error() string

type ErrPassphraseRequired 

type ErrPassphraseRequired struct{}

ErrPassphraseRequired is returned when an attempt is made to read an encrypted block without a passphrase.

func (*ErrPassphraseRequired) Error 

func (*ErrPassphraseRequired) Error() string

type IndirectPrivateKey 

type IndirectPrivateKey interface {
	// Next returns either the key to be returned immediately, or data
	// to be parsed as per a normal PEM block.
	Next(ctx context.Context, passphrase []byte) (crypto.PrivateKey, []byte)
	String() string
}

IndirectPrivateKey represents the interface returned when an 'indirect' PEM block is encountered by registrar.ParsePrivateKey.

type MarshalPrivateKeyFunc 

type MarshalPrivateKeyFunc func(key crypto.PrivateKey, passphrase []byte) ([]byte, error)

MarshalPrivateKeyFunc marshals the supplied key to PEM optionally encrypting it using the supplied passphrase.

type MarshalPublicKeyFunc 

type MarshalPublicKeyFunc func(crypto.PublicKey) ([]byte, error)

MarshalPublicKeyFunc marshals the supplied key to PEM.

type ParsePrivateKeyFunc 

type ParsePrivateKeyFunc func(block *pem.Block) (crypto.PrivateKey, error)

ParsePrivateKeyFunc parses a private key from PEM.

type ParsePublicKeyFunc 

type ParsePublicKeyFunc func(block *pem.Block) (crypto.PublicKey, error)

ParsePublicKeyFunc parses a public key from PEM.

type ParsePublicKeyTextFunc 

type ParsePublicKeyTextFunc func(data []byte) (crypto.PublicKey, error)

ParsePublicKeyTextFunc parses a public key from a format other than PEM.

type Registrar 

type Registrar struct {
	// contains filtered or unexported fields
}

Registrar represents an extensible collection of functions for marshaling and parsing keys. Functions are registered with it for performing marshaling, parsing and 'API' (e.g. creating a new Signer) operations and thus provides a uniform interface for working with keys of many different

func NewRegistrar 

func NewRegistrar() *Registrar

NewRegistrar returns an intialized instance of Registrar.

func (*Registrar) APIForKey 

func (r *Registrar) APIForKey(key crypto.PrivateKey) (API, error)

APIForKey returns the interface instance registered for the supplied key.

func (*Registrar) MarshalPrivateKey 

func (r *Registrar) MarshalPrivateKey(key crypto.PrivateKey, passphrase []byte) ([]byte, error)

MarshalPrivateKey marshals key into a PEM block using the appropriately registered function.

func (*Registrar) MarshalPublicKey 

func (r *Registrar) MarshalPublicKey(key crypto.PublicKey) ([]byte, error)

MarshalPublicKey marshals key into a PEM block using the appropriately registered function.

func (*Registrar) ParsePrivateKey 

func (r *Registrar) ParsePrivateKey(ctx context.Context, data, passphrase []byte) (crypto.PrivateKey, error)

ParsePublicKey parsers the supplied PEM data using the registered parsers to obtain a private key. It will follow at most one 'indirect' PEM block.

func (*Registrar) ParsePublicKey 

func (r *Registrar) ParsePublicKey(data []byte) (crypto.PublicKey, error)

ParsePublicKey parsers the supplied PEM (or plain text) data using the registered parsers to obtain a public key.

func (*Registrar) RegisterAPI 

func (r *Registrar) RegisterAPI(ifc API, types ...interface{}) error

RegisterAPI registers the supplied interface instance as providing 'API' operations for the specified types. This interface instance is returned by APIForKey when called for the specified types.

func (*Registrar) RegisterDecrypter 

func (r *Registrar) RegisterDecrypter(decrypter DecryptFunc, pemType string, matcher func(*pem.Block) bool)

RegisterDecrypter registers the supplied function for decrypting the contents of the specified PEM types. It is called internally by ParsePrivateKey.

func (*Registrar) RegisterIndirectPrivateKeyParser 

func (r *Registrar) RegisterIndirectPrivateKeyParser(parser ParsePrivateKeyFunc, pemHeaderValue string)

RegisterIndirectPrivateKeyParser registers the supplied function as an 'indirect' parser for PEM blocks of type IndirectionPrivateKeyPEMType which have the specified value for their IndirectionTypePEMHeader header. See IndirectMatcherFunc and MarshalFuncForIndirection. This facility is typically used to avoid copying private key files and for using external agents/services to host private key files and associated signing operations.

func (*Registrar) RegisterPrivateKeyMarshaler 

func (r *Registrar) RegisterPrivateKeyMarshaler(fn MarshalPrivateKeyFunc, types ...interface{})

RegisterPrivateKeyMarshaler registers the supplied function for marshaling the specified types. These functions will be called by MarshalPrivateKey when marshaling the specified types.

func (*Registrar) RegisterPrivateKeyParser 

func (r *Registrar) RegisterPrivateKeyParser(parser ParsePrivateKeyFunc, pemType string, matcher func(*pem.Block) bool)

RegisterPrivateKeyParser registers the supplied function for parsing the specified PME types. These functions will be called by ParsePrivateKey when that PEM type is encountered.

func (*Registrar) RegisterPublicKeyMarshaler 

func (r *Registrar) RegisterPublicKeyMarshaler(fn MarshalPublicKeyFunc, types ...interface{})

RegisterPublicKeyMarshaler registers the supplied function for marshaling the specified types. These functions will be called by MarshalPublicKey when marshaling the specified types.

func (*Registrar) RegisterPublicKeyParser 

func (r *Registrar) RegisterPublicKeyParser(parser ParsePublicKeyFunc, pemType string, matcher func(*pem.Block) bool)

RegisterPublicKeyParser registers the supplied function for parsing the specified PME types. These functions will be called by ParsePublicKey when that PEM type is encountered.

func (*Registrar) RegisterPublicKeyTextParser 

func (r *Registrar) RegisterPublicKeyTextParser(parser ParsePublicKeyTextFunc)

RegisterPublicKeyTextParser adds the parser to the list of parsers to be used for parsing formats other than PEM. For example SSH public keys are not in PEM format.

Source Files

View all Source files

Directories

Path Synopsis
Package indirectkeyfiles provides support for key files whose contents refer to another keyfile.
 Package indirectkeyfiles provides support for key files whose contents refer to another keyfile.
Package sshkeys provides support for using ssh keys with the security/keys package, including private keys hosted within an ssh agent.
 Package sshkeys provides support for using ssh keys with the security/keys package, including private keys hosted within an ssh agent.
Package x509 provides support for using x509/ssl keys with the security/keys package.
 Package x509 provides support for using x509/ssl keys with the security/keys package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.