keys

package
v0.0.0-...-a1881e9 Latest Latest
Warning

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

 Go to latest Published: Dec 19, 2024 License: Apache-2.0 Imports: 18 Imported by: 25

Documentation

Overview

Package keys defines common interfaces for Teleport client keys.

Index

Constants

View Source 
const (
	PKCS1PrivateKeyType   = "RSA PRIVATE KEY"
	PKCS8PrivateKeyType   = "PRIVATE KEY"
	ECPrivateKeyType      = "EC PRIVATE KEY"
	OpenSSHPrivateKeyType = "OPENSSH PRIVATE KEY"
)
View Source 
const (
	// PKCS1PublicKeyType is the PEM encoding type commonly used for PKCS#1, ASN.1 DER form public keys.
	PKCS1PublicKeyType = "RSA PUBLIC KEY"
	// PKIXPublicKeyType is the PEM encoding type commonly used for PKIX, ASN.1 DER form public keys.
	PKIXPublicKeyType = "PUBLIC KEY"
)

Variables

This section is empty.

Functions

func AssertSoftwarePrivateKey 

func AssertSoftwarePrivateKey(privKey []byte) error

AssertSoftwarePrivateKey returns nil if the given private key PEM looks like a raw software private key as opposed to a hardware key (yubikey). This function does a similar check to ParsePrivateKey, followed by key.SoftwarePrivateKeyPEM() without parsing the private fully into a crypto.Signer. This reduces the time it takes to check if a private key is a software private key and improves the performance compared to ParsePrivateKey by a factor of 20.

func IsPrivateKeyPolicyError 

func IsPrivateKeyPolicyError(err error) bool

IsPrivateKeyPolicyError returns true if the given error is a private key policy error.

func LoadX509KeyPair 

func LoadX509KeyPair(certFile, keyFile string) (tls.Certificate, error)

LoadX509KeyPair parse a tls.Certificate from a private key file and certificate file. This should be used instead of tls.LoadX509KeyPair to support non-raw private keys, like PIV keys.

func MarshalPrivateKey 

func MarshalPrivateKey(key crypto.Signer) ([]byte, error)

MarshalPrivateKey will return a PEM encoded crypto.Signer. Only supports rsa, ecdsa, and ed25519 keys.

func MarshalPublicKey 

func MarshalPublicKey(pub crypto.PublicKey) ([]byte, error)

MarshalPublicKey returns a PEM encoding of the given public key. Encodes RSA keys in PKCS1 format for backward compatibility. All other key types are encoded in PKIX, ASN.1 DER form. Only supports *rsa.PublicKey, *ecdsa.PublicKey, and ed25519.PublicKey.

func MarshalSoftwarePrivateKeyPKCS8DER 

func MarshalSoftwarePrivateKeyPKCS8DER(signer crypto.Signer) ([]byte, error)

MarshalSoftwarePrivateKeyPKCS8DER marshals the provided private key as PKCS#8 DER.

func NewPrivateKeyPolicyError 

func NewPrivateKeyPolicyError(p PrivateKeyPolicy) error

func ParsePublicKey 

func ParsePublicKey(keyPEM []byte) (crypto.PublicKey, error)

ParsePublicKey parses a PEM-encoded public key. Supports PEM encodings of PKCS#1 or PKIX ASN.1 DER form public keys.

func TLSCertificateForSigner 

func TLSCertificateForSigner(signer crypto.Signer, certPEMBlock []byte) (tls.Certificate, error)

TLSCertificate parses the given TLS certificate(s) paired with the given signer to return a tls.Certificate, ready to be used in a TLS handshake.

func X509Certificate 

func X509Certificate(certPEMBlock []byte) (*x509.Certificate, [][]byte, error)

X509Certificate takes a PEM-encoded file containing one or more certificates, extracts all certificates, and parses the Leaf certificate (the first one in the chain). If you are loading both a certificate and a private key, you should use X509KeyPair instead.

func X509KeyPair 

func X509KeyPair(certPEMBlock, keyPEMBlock []byte) (tls.Certificate, error)

X509KeyPair parse a tls.Certificate from a private key PEM and certificate PEM. This should be used instead of tls.X509KeyPair to support non-raw private keys, like PIV keys.

Types

type AttestationData 

type AttestationData struct {
	// PublicKeyDER is the public key in PKIX, ASN.1 DER form.
	PublicKeyDER []byte `json:"public_key"`
	// PrivateKeyPolicy specifies the private key policy supported by the associated private key.
	PrivateKeyPolicy PrivateKeyPolicy `json:"private_key_policy"`
	// SerialNumber is the serial number of the Attested hardware key.
	SerialNumber uint32 `json:"serial_number"`
}

AttestationData is verified attestation data for a public key.

type AttestationStatement 

type AttestationStatement attestation.AttestationStatement

AttestationStatement is an attestation statement for a hardware private key that supports json marshaling through the standard json/encoding package.

func AttestationStatementFromProto 

func AttestationStatementFromProto(att *attestation.AttestationStatement) *AttestationStatement

AttestationStatementFromProto converts an AttestationStatement from its protobuf form.

func (*AttestationStatement) MarshalJSON 

func (ar *AttestationStatement) MarshalJSON() ([]byte, error)

MarshalJSON implements custom protobuf json marshaling.

func (*AttestationStatement) ToProto 

func (ar *AttestationStatement) ToProto() *attestation.AttestationStatement

ToProto converts this AttestationStatement to its protobuf form.

func (*AttestationStatement) UnmarshalJSON 

func (ar *AttestationStatement) UnmarshalJSON(buf []byte) error

UnmarshalJSON implements custom protobuf json unmarshaling.

type HardwareKeyPrompt 

type HardwareKeyPrompt interface {
	// AskPIN prompts the user for a PIN.
	// The requirement tells if the PIN is required or optional.
	AskPIN(ctx context.Context, requirement PINPromptRequirement) (string, error)
	// Touch prompts the user to touch the hardware key.
	Touch(ctx context.Context) error
	// ChangePIN asks for a new PIN.
	// If the PUK has a default value, it should ask for the new value for it.
	// It is up to the implementer how the validation is handled.
	// For example, CLI prompt can ask for a valid PIN/PUK in a loop, a GUI
	// prompt can use the frontend validation.
	ChangePIN(ctx context.Context) (*PINAndPUK, error)
	// ConfirmSlotOverwrite asks the user if the slot's private key and certificate can be overridden.
	ConfirmSlotOverwrite(ctx context.Context, message string) (bool, error)
}

HardwareKeyPrompt provides methods to interact with a YubiKey hardware key.

type HardwareSigner 

type HardwareSigner interface {
	crypto.Signer

	// GetAttestationStatement returns an AttestationStatement for this private key.
	GetAttestationStatement() *AttestationStatement

	// GetPrivateKeyPolicy returns the PrivateKeyPolicy supported by this private key.
	GetPrivateKeyPolicy() PrivateKeyPolicy
}

HardwareSigner is a crypto.Signer which can be attested as being backed by a hardware key. This enables the ability to enforce hardware key private key policies.

type PINAndPUK 

type PINAndPUK struct {
	// New PIN set by the user.
	PIN string
	// PUK used to change the PIN.
	// This is a new PUK if it has not been changed (from the default PUK).
	PUK string
	// PUKChanged is true if the user changed the default PUK.
	PUKChanged bool
}

PINAndPUK describes a response returned from HardwareKeyPrompt.ChangePIN.

type PINPromptRequirement 

type PINPromptRequirement int

PINPromptRequirement specifies whether a PIN is required. 

const (
	// PINOptional allows the user to proceed without entering a PIN.
	PINOptional PINPromptRequirement = iota
	// PINRequired enforces that a PIN must be entered to proceed.
	PINRequired
)

type PIVSlot 

type PIVSlot string

PIVSlot is the string representation of a PIV slot. e.g. "9a".

func (PIVSlot) Validate 

func (s PIVSlot) Validate() error

Validate that the PIV slot is a valid value.

type ParsePrivateKeyOpt 

type ParsePrivateKeyOpt func(o *ParsePrivateKeyOptions)

ParsePrivateKeyOpt applies configuration options.

func WithCustomPrompt 

func WithCustomPrompt(prompt HardwareKeyPrompt) ParsePrivateKeyOpt

WithCustomPrompt sets a custom hardware key prompt.

type ParsePrivateKeyOptions 

type ParsePrivateKeyOptions struct {
	// CustomHardwareKeyPrompt is a custom hardware key prompt to use when asking
	// for a hardware key PIN, touch, etc.
	// If empty, a default CLI prompt is used.
	CustomHardwareKeyPrompt HardwareKeyPrompt
}

ParsePrivateKeyOptions contains config options for ParsePrivateKey.

type PrivateKey 

type PrivateKey struct {
	crypto.Signer
	// contains filtered or unexported fields
}

PrivateKey implements crypto.Signer with additional helper methods. The underlying private key may be a standard crypto.Signer implemented in the standard library (aka *rsa.PrivateKey, *ecdsa.PrivateKey, or ed25519.PrivateKey), or it may be a custom implementation for a non-standard private key, such as a hardware key.

func GetYubiKeyPrivateKey 

func GetYubiKeyPrivateKey(ctx context.Context, policy PrivateKeyPolicy, slot PIVSlot, customPrompt HardwareKeyPrompt) (*PrivateKey, error)

GetYubiKeyPrivateKey attempt to retrieve a YubiKey private key matching the given hardware key policy from the given slot. If slot is unspecified, the default slot for the given key policy will be used. If the slot is empty, a new private key matching the given policy will be generated in the slot.

  • hardware_key: 9a
  • hardware_key_touch: 9c
  • hardware_key_pin: 9d
  • hardware_key_touch_pin: 9e

func LoadKeyPair 

func LoadKeyPair(privFile, sshPubFile string, customPrompt HardwareKeyPrompt) (*PrivateKey, error)

LoadKeyPair returns the PrivateKey for the given private and public key files.

func LoadPrivateKey 

func LoadPrivateKey(keyFile string) (*PrivateKey, error)

LoadPrivateKey returns the PrivateKey for the given key file.

func NewPrivateKey 

func NewPrivateKey(signer crypto.Signer, keyPEM []byte) (*PrivateKey, error)

NewPrivateKey returns a new PrivateKey for the given crypto.Signer with a pre-marshaled private key PEM, which may be a special PIV key PEM.

func NewSoftwarePrivateKey 

func NewSoftwarePrivateKey(signer crypto.Signer) (*PrivateKey, error)

NewSoftwarePrivateKey returns a new PrivateKey for a crypto.Signer. [signer] must be an *rsa.PrivateKey, *ecdsa.PrivateKey, or ed25519.PrivateKey.

func ParseKeyPair 

func ParseKeyPair(privPEM, marshaledSSHPub []byte, customPrompt HardwareKeyPrompt) (*PrivateKey, error)

ParseKeyPair returns the PrivateKey for the given private and public key PEM blocks.

func ParsePrivateKey 

func ParsePrivateKey(keyPEM []byte, opts ...ParsePrivateKeyOpt) (*PrivateKey, error)

ParsePrivateKey returns the PrivateKey for the given key PEM block. Allows passing a custom hardware key prompt.

func (*PrivateKey) GetAttestationStatement 

func (k *PrivateKey) GetAttestationStatement() *AttestationStatement

GetAttestationStatement returns this key's AttestationStatement. If the key is not a hardware-backed key, this method returns nil.

func (*PrivateKey) GetPrivateKeyPolicy 

func (k *PrivateKey) GetPrivateKeyPolicy() PrivateKeyPolicy

GetPrivateKeyPolicy returns this key's PrivateKeyPolicy.

func (*PrivateKey) IsHardware 

func (k *PrivateKey) IsHardware() bool

IsHardware returns true if [k] is a hardware PIV key.

func (*PrivateKey) MarshalSSHPrivateKey 

func (k *PrivateKey) MarshalSSHPrivateKey() ([]byte, error)

MarshalSSHPrivateKey returns the private key marshaled to: - PEM-encoded OpenSSH format for Ed25519 or ECDSA keys - PEM-encoded PKCS#1 for RSA keys - a custom PEM-encoded format for PIV keys

func (*PrivateKey) MarshalSSHPublicKey 

func (k *PrivateKey) MarshalSSHPublicKey() []byte

MarshalSSHPublicKey returns the public key marshaled to SSH authorized_keys format.

func (*PrivateKey) MarshalTLSPublicKey 

func (k *PrivateKey) MarshalTLSPublicKey() ([]byte, error)

MarshalTLSPublicKey returns a PEM encoding of the public key. Encodes RSA keys in PKCS1 format for backward compatibility. All other key types are encoded in PKIX, ASN.1 DER form. Only supports *rsa.PublicKey, *ecdsa.PublicKey, and ed25519.PublicKey.

func (*PrivateKey) PPKFile 

func (k *PrivateKey) PPKFile() ([]byte, error)

PPKFile returns a PuTTY PPK-formatted keypair

func (*PrivateKey) PrivateKeyPEM 

func (k *PrivateKey) PrivateKeyPEM() []byte

PrivateKeyPEM returns PEM encoded private key data. This may be data necessary to retrieve the key, such as a YubiKey serial number and slot, or it can be a PKCS marshaled private key.

The resulting PEM encoded data should only be decoded with ParsePrivateKey to prevent errors from parsing non PKCS marshaled keys, such as a PIV key.

func (*PrivateKey) SSHPublicKey 

func (k *PrivateKey) SSHPublicKey() ssh.PublicKey

SSHPublicKey returns the ssh.PublicKey representation of the public key.

func (*PrivateKey) SoftwarePrivateKeyPEM 

func (k *PrivateKey) SoftwarePrivateKeyPEM() ([]byte, error)

SoftwarePrivateKeyPEM returns the PEM encoding of the private key. If the key is not a raw software RSA, ECDSA, or Ed25519 key, then an error will be returned.

This is used by some integrations which currently only support raw software private keys as opposed to hardware keys (yubikeys), like Kubernetes, MongoDB, and PPK files for windows.

func (*PrivateKey) TLSCertificate 

func (k *PrivateKey) TLSCertificate(certPEMBlock []byte) (tls.Certificate, error)

TLSCertificate parses the given TLS certificate(s) paired with the private key to return a tls.Certificate, ready to be used in a TLS handshake.

type PrivateKeyPolicy 

type PrivateKeyPolicy string

PrivateKeyPolicy is a requirement for client private key storage. 

const (
	// PrivateKeyPolicyNone means that the client can store their private keys
	// anywhere (usually on disk).
	PrivateKeyPolicyNone PrivateKeyPolicy = "none"
	// PrivateKeyPolicyHardwareKey means that the client must use a valid
	// hardware key to generate and store their private keys securely.
	PrivateKeyPolicyHardwareKey PrivateKeyPolicy = "hardware_key"
	// PrivateKeyPolicyHardwareKeyTouch means that the client must use a valid
	// hardware key to generate and store their private keys securely, and
	// this key must require touch to be accessed and used.
	PrivateKeyPolicyHardwareKeyTouch PrivateKeyPolicy = "hardware_key_touch"
	// PrivateKeyPolicyHardwareKeyPIN means that the client must use a valid
	// hardware key to generate and store their private keys securely, and
	// this key must require pin to be accessed and used.
	PrivateKeyPolicyHardwareKeyPIN PrivateKeyPolicy = "hardware_key_pin"
	// PrivateKeyPolicyHardwareKeyTouchAndPIN means that the client must use a valid
	// hardware key to generate and store their private keys securely, and
	// this key must require touch and pin to be accessed and used.
	PrivateKeyPolicyHardwareKeyTouchAndPIN PrivateKeyPolicy = "hardware_key_touch_and_pin"
	// PrivateKeyPolicyWebSession is a special case used for Web Sessions. This policy
	// implies that the client private key and certificate are stored in the Proxy
	// Process Memory and Auth Storage. These certs do not leave the Proxy/Auth
	// services, but the Web Client receives a Web Cookie which can be used to
	// make requests with the server-side client key+cert.
	//
	// This policy does not provide the same hardware key guarantee as the above policies.
	// Instead, this policy must be accompanied by WebAuthn prompts for important operations
	// in order to pass hardware key policy requirements.
	PrivateKeyPolicyWebSession PrivateKeyPolicy = "web_session"
)

func ParsePrivateKeyPolicyError 

func ParsePrivateKeyPolicyError(err error) (PrivateKeyPolicy, error)

ParsePrivateKeyPolicyError checks if the given error is a private key policy error and returns the contained unsatisfied PrivateKeyPolicy.

func PolicyThatSatisfiesSet 

func PolicyThatSatisfiesSet(policies []PrivateKeyPolicy) (PrivateKeyPolicy, error)

PolicyThatSatisfiesSet returns least restrictive policy necessary to satisfy the given set of policies.

func (PrivateKeyPolicy) IsHardwareKeyPolicy 

func (p PrivateKeyPolicy) IsHardwareKeyPolicy() bool

IsHardwareKeyPolicy return true if this private key policy requires a hardware key.

func (PrivateKeyPolicy) IsSatisfiedBy 

func (requiredPolicy PrivateKeyPolicy) IsSatisfiedBy(keyPolicy PrivateKeyPolicy) bool

IsSatisfiedBy returns whether this key policy is satisfied by the given key policy.

func (PrivateKeyPolicy) MFAVerified 

func (p PrivateKeyPolicy) MFAVerified() bool

MFAVerified checks that private keys with this key policy count as MFA verified. Both Hardware key touch and pin are count as MFA verification.

Note: MFA checks with private key policies are only performed during the establishment of the connection, during the TLS/SSH handshake. For long term connections, MFA should be re-verified through other methods (e.g. webauthn).

Source Files

View all Source files

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.