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
- func DecryptPEMBlock(block *pem.Block, passphrase []byte) (*pem.Block, crypto.PrivateKey, error)
- func DecryptPKCS8Block(block *pem.Block, passphrase []byte) (*pem.Block, crypto.PrivateKey, error)
- func IndirectMatcherFunc(indirectionType string) func(b *pem.Block) bool
- func MarshalFuncForIndirection(indirectionType string) func(contents []byte) ([]byte, error)
- func MarshalPKCS8PrivateKey(key crypto.PrivateKey, passphrase []byte) ([]byte, error)
- func MarshalPKIXPublicKey(key crypto.PublicKey) ([]byte, error)
- func MustRegister(r *Registrar)
- func NewPrivateKeyForAlgo(algo CryptoAlgo) (crypto.PrivateKey, error)
- func ParseECPrivateKey(block *pem.Block) (crypto.PrivateKey, error)
- func ParsePKCS8PrivateKey(block *pem.Block) (crypto.PrivateKey, error)
- func ParsePKIXPublicKey(block *pem.Block) (crypto.PublicKey, error)
- func Register(r *Registrar) error
- func ZeroPassphrase(pass []byte)
- type API
- type CryptoAlgo
- type DecryptFunc
- type ErrBadPassphrase
- type ErrPassphraseRequired
- type IndirectPrivateKey
- type MarshalPrivateKeyFunc
- type MarshalPublicKeyFunc
- type ParsePrivateKeyFunc
- type ParsePublicKeyFunc
- type ParsePublicKeyTextFunc
- type Registrar
- func (r *Registrar) APIForKey(key crypto.PrivateKey) (API, error)
- func (r *Registrar) MarshalPrivateKey(key crypto.PrivateKey, passphrase []byte) ([]byte, error)
- func (r *Registrar) MarshalPublicKey(key crypto.PublicKey) ([]byte, error)
- func (r *Registrar) ParsePrivateKey(ctx context.Context, data, passphrase []byte) (crypto.PrivateKey, error)
- func (r *Registrar) ParsePublicKey(data []byte) (crypto.PublicKey, error)
- func (r *Registrar) RegisterAPI(ifc API, types ...interface{}) error
- func (r *Registrar) RegisterDecrypter(decrypter DecryptFunc, pemType string, matcher func(*pem.Block) bool)
- func (r *Registrar) RegisterIndirectPrivateKeyParser(parser ParsePrivateKeyFunc, pemHeaderValue string)
- func (r *Registrar) RegisterPrivateKeyMarshaler(fn MarshalPrivateKeyFunc, types ...interface{})
- func (r *Registrar) RegisterPrivateKeyParser(parser ParsePrivateKeyFunc, pemType string, matcher func(*pem.Block) bool)
- func (r *Registrar) RegisterPublicKeyMarshaler(fn MarshalPublicKeyFunc, types ...interface{})
- func (r *Registrar) RegisterPublicKeyParser(parser ParsePublicKeyFunc, pemType string, matcher func(*pem.Block) bool)
- func (r *Registrar) RegisterPublicKeyTextParser(parser ParsePublicKeyTextFunc)
Constants ¶
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 ¶
DecryptPEMBlock decrypts an encrypted PEM block. Deprecated: use PKCS8 encryption instead.
func DecryptPKCS8Block ¶
DecryptPKCS8Block decrypts a private key encrypted using PKCS8. The block's PEM type must be "ENCRYPTED PRIVATE KEY".
func IndirectMatcherFunc ¶
IndirectMatcherFunc returns a function that can be used to match an 'indirect' PEM block's IndirectionTypePEMHeader.
func MarshalFuncForIndirection ¶
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 ¶
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 ¶
ParsePKIXPublicKey calls x509.ParsePKIXPublicKey with block.Bytes.
func Register ¶
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.
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 ¶
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 ¶
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 ¶
ParsePublicKeyFunc parses a public key from PEM.
type ParsePublicKeyTextFunc ¶
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 ¶
MarshalPrivateKey marshals key into a PEM block using the appropriately registered function.
func (*Registrar) MarshalPublicKey ¶
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 ¶
ParsePublicKey parsers the supplied PEM (or plain text) data using the registered parsers to obtain a public key.
func (*Registrar) RegisterAPI ¶
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.
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. |