apiv1

type AlreadyExistsError ¶ added in v0.20.0

type AlreadyExistsError struct {
	Message string
}

AlreadyExistsError is the type of error returned if a key already exists. This is currently only implemented for pkcs11, tpmkms, and mackms.

func (e AlreadyExistsError) Error() string

func (e AlreadyExistsError) Is(target error) bool

type AttestationClient ¶ added in v0.32.0

type AttestationClient interface {
	Attest(context.Context) ([]*x509.Certificate, error)
}

AttestationClient is an interface that provides a pluggable method for attesting Attestation Keys (AKs).

type Attester ¶ added in v0.19.0

type Attester interface {
	CreateAttestation(req *CreateAttestationRequest) (*CreateAttestationResponse, error)
}

Attester is the interface implemented by the KMS that can respond with an attestation certificate or key.

Experimental ¶

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

type CertificateChainManager ¶ added in v0.32.0

type CertificateChainManager interface {
	LoadCertificateChain(req *LoadCertificateChainRequest) ([]*x509.Certificate, error)
	StoreCertificateChain(req *StoreCertificateChainRequest) error
}

CertificateChainManager is the interface implemented by KMS implementations that can load certificate chains. The LoadCertificateChain method uses the same request object as the LoadCertificate method of the CertificateManager interfaces. When the LoadCertificateChain method is called, the certificate chain stored through the CertificateChain property in the StoreCertificateRequest will be returned, partially reusing the StoreCertificateRequest object.

type CertificateManager ¶

type CertificateManager interface {
	LoadCertificate(req *LoadCertificateRequest) (*x509.Certificate, error)
	StoreCertificate(req *StoreCertificateRequest) error
}

CertificateManager is the interface implemented by the KMS that can load and store x509.Certificates.

type CertificationParameters ¶ added in v0.32.0

type CertificationParameters struct {
	// Public represents the key's canonical encoding (a TPMT_PUBLIC structure).
	// It includes the public key and signing parameters.
	Public []byte
	// CreateData represents the properties of a TPM 2.0 key. It is encoded
	// as a TPMS_CREATION_DATA structure.
	CreateData []byte
	// CreateAttestation represents an assertion as to the details of the key.
	// It is encoded as a TPMS_ATTEST structure.
	CreateAttestation []byte
	// CreateSignature represents a signature of the CreateAttestation structure.
	// It is encoded as a TPMT_SIGNATURE structure.
	CreateSignature []byte
}

CertificationParameters encapsulates the inputs for certifying an application key. Only TPM 2.0 is supported at this point.

This struct was copied from github.com/google/go-attestation, preventing an additional dependency in this package.

type CreateAttestationRequest ¶ added in v0.19.0

type CreateAttestationRequest struct {
	Name              string
	AttestationClient AttestationClient // TODO(hs): a better name; Attestor perhaps, but that's already taken
}

CreateAttestationRequest is the parameter used in the kms.CreateAttestation method.

Experimental ¶

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

type CreateAttestationResponse ¶ added in v0.19.0

type CreateAttestationResponse struct {
	Certificate             *x509.Certificate
	CertificateChain        []*x509.Certificate
	PublicKey               crypto.PublicKey
	CertificationParameters *CertificationParameters
	PermanentIdentifier     string
}

CreateAttestationResponse is the response value of the kms.CreateAttestation method.

If a non-empty CertificateChain is returned, the first x509.Certificate is the same as the one in the Certificate property.

When an attestation is created for a TPM key, the CertificationParameters property will have a record of the certification parameters at the time of key attestation.

Experimental ¶

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

type CreateDecrypterRequest ¶

type CreateDecrypterRequest struct {
	Decrypter        crypto.Decrypter
	DecryptionKey    string
	DecryptionKeyPEM []byte
	Password         []byte
	PasswordPrompter PasswordPrompter
}

CreateDecrypterRequest is the parameter used in the kms.Decrypt method.

type CreateKeyRequest ¶

type CreateKeyRequest struct {
	// Name represents the key name or label used to identify a key.
	//
	// Used by: awskms, cloudkms, azurekms, pkcs11, yubikey, tpmkms, mackms.
	Name string

	// SignatureAlgorithm represents the type of key to create.
	SignatureAlgorithm SignatureAlgorithm

	// Bits is the number of bits on RSA keys.
	Bits int

	// ProtectionLevel specifies how cryptographic operations are performed.
	// Used by: cloudkms, azurekms.
	ProtectionLevel ProtectionLevel

	// Extractable defines if the new key may be exported from the HSM under a
	// wrap key. On pkcs11 sets the CKA_EXTRACTABLE bit.
	//
	// Used by: pkcs11
	Extractable bool

	// PINPolicy defines PIN requirements when signing or decrypting with an
	// asymmetric key.
	//
	// Used by: yubikey
	PINPolicy PINPolicy

	// TouchPolicy represents proof-of-presence requirements when signing or
	// decrypting with asymmetric key in a given slot.
	//
	// Used by: yubikey
	TouchPolicy TouchPolicy

	// DestroyRetentionPeriod is the period of time that a key spends in a
	// destroy scheduled state before transitioning to destroyed.
	//
	// Used by: cloudkms
	DestroyRetentionPeriod time.Duration
}

CreateKeyRequest is the parameter used in the kms.CreateKey method.

type CreateKeyResponse ¶

type CreateKeyResponse struct {
	Name      string
	PublicKey crypto.PublicKey
	// PrivateKey is only used by softkms
	PrivateKey          crypto.PrivateKey
	CreateSignerRequest CreateSignerRequest
}

CreateKeyResponse is the response value of the kms.CreateKey method.

type CreateSignerRequest ¶

type CreateSignerRequest struct {
	Signer           crypto.Signer
	SigningKey       string
	SigningKeyPEM    []byte
	TokenLabel       string
	PublicKey        string
	PublicKeyPEM     []byte
	Password         []byte
	PasswordPrompter PasswordPrompter
}

CreateSignerRequest is the parameter used in the kms.CreateSigner method.

type Decrypter ¶

type Decrypter interface {
	CreateDecrypter(req *CreateDecrypterRequest) (crypto.Decrypter, error)
}

Decrypter is an interface implemented by KMSes that are used in operations that require decryption

type DeleteCertificateRequest ¶ added in v0.44.0

type DeleteCertificateRequest struct {
	Name string
}

DeleteCertificateRequest is the parameter used in the kms.DeleteCertificate method.

Experimental ¶

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

type DeleteKeyRequest ¶ added in v0.44.0

type DeleteKeyRequest struct {
	Name string
}

DeleteKeyRequest is the parameter used in the kms.DeleteKey method.

Experimental ¶

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

type GetPublicKeyRequest ¶

type GetPublicKeyRequest struct {
	Name string
}

GetPublicKeyRequest is the parameter used in the kms.GetPublicKey method.

type KeyManager ¶

type KeyManager interface {
	GetPublicKey(req *GetPublicKeyRequest) (crypto.PublicKey, error)
	CreateKey(req *CreateKeyRequest) (*CreateKeyResponse, error)
	CreateSigner(req *CreateSignerRequest) (crypto.Signer, error)
	Close() error
}

KeyManager is the interface implemented by all the KMS.

type KeyManagerNewFunc ¶

type KeyManagerNewFunc func(ctx context.Context, opts Options) (KeyManager, error)

KeyManagerNewFunc is the type that represents the method to initialize a new KeyManager.

func LoadKeyManagerNewFunc(t Type) (KeyManagerNewFunc, bool)

type LoadCertificateChainRequest ¶ added in v0.32.0

type LoadCertificateChainRequest LoadCertificateRequest

LoadCertificateChainRequest is the parameter used in the LoadCertificateChain method of a CertificateChainManager. It's an alias for LoadCertificateRequest.

type LoadCertificateRequest ¶

type LoadCertificateRequest struct {
	Name string
}

LoadCertificateRequest is the parameter used in the LoadCertificate method of a CertificateManager.

type NameValidator ¶

type NameValidator interface {
	ValidateName(s string) error
}

NameValidator is an interface that KeyManager can implement to validate a given name or URI.

type NotFoundError ¶ added in v0.44.1

type NotFoundError struct {
	Message string
}

NotFoundError is the type of error returned if a key or certificate does not exist. This is currently only implemented for capi and mackms.

func (e NotFoundError) Error() string

func (e NotFoundError) Is(target error) bool

type NotImplementedError ¶ added in v0.20.0

type NotImplementedError struct {
	Message string
}

NotImplementedError is the type of error returned if an operation is not implemented.

func (e NotImplementedError) Error() string

func (e NotImplementedError) Is(target error) bool

type Options ¶

type Options struct {
	// The type of the KMS to use.
	Type Type `json:"type"`

	// Path to the credentials file used in CloudKMS and AmazonKMS.
	CredentialsFile string `json:"credentialsFile,omitempty"`

	// URI is based on the PKCS #11 URI Scheme defined in
	// https://tools.ietf.org/html/rfc7512 and represents the configuration used
	// to connect to the KMS.
	//
	// Used by: pkcs11, tpmkms
	URI string `json:"uri,omitempty"`

	// Pin used to access the PKCS11 module. It can be defined in the URI using
	// the pin-value or pin-source properties.
	Pin string `json:"pin,omitempty"`

	// ManagementKey used in YubiKeys. Default management key is the hexadecimal
	// string 010203040506070801020304050607080102030405060708:
	//   []byte{
	//       0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
	//       0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
	//       0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
	//   }
	ManagementKey string `json:"managementKey,omitempty"`

	// Region to use in AmazonKMS.
	Region string `json:"region,omitempty"`

	// Profile to use in AmazonKMS.
	Profile string `json:"profile,omitempty"`

	// StorageDirectory is the path to a directory to
	// store serialized TPM objects. Only used by the TPMKMS.
	StorageDirectory string `json:"storageDirectory,omitempty"`
}

Options are the KMS options. They represent the kms object in the ca.json.

func (o *Options) GetType() (Type, error)

func (o *Options) Validate() error

type PINPolicy ¶ added in v0.21.0

type PINPolicy int

PINPolicy represents PIN requirements when signing or decrypting with an asymmetric key in a given slot. PINPolicy is used by the YubiKey KMS.

const (
	PINPolicyNever PINPolicy = iota + 1
	PINPolicyOnce
	PINPolicyAlways
)

type PasswordPrompter ¶ added in v0.35.0

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

type ProtectionLevel ¶

type ProtectionLevel int

ProtectionLevel specifies on some KMS how cryptographic operations are performed.

const (
	// Protection level not specified.
	UnspecifiedProtectionLevel ProtectionLevel = iota
	// Crypto operations are performed in software.
	Software
	// Crypto operations are performed in a Hardware Security Module.
	HSM
)

func (p ProtectionLevel) String() string

type SignatureAlgorithm ¶

type SignatureAlgorithm int

SignatureAlgorithm used for cryptographic signing.

const (
	// Not specified.
	UnspecifiedSignAlgorithm SignatureAlgorithm = iota
	// RSASSA-PKCS1-v1_5 key and a SHA256 digest.
	SHA256WithRSA
	// RSASSA-PKCS1-v1_5 key and a SHA384 digest.
	SHA384WithRSA
	// RSASSA-PKCS1-v1_5 key and a SHA512 digest.
	SHA512WithRSA
	// RSASSA-PSS key with a SHA256 digest.
	SHA256WithRSAPSS
	// RSASSA-PSS key with a SHA384 digest.
	SHA384WithRSAPSS
	// RSASSA-PSS key with a SHA512 digest.
	SHA512WithRSAPSS
	// ECDSA on the NIST P-256 curve with a SHA256 digest.
	ECDSAWithSHA256
	// ECDSA on the NIST P-384 curve with a SHA384 digest.
	ECDSAWithSHA384
	// ECDSA on the NIST P-521 curve with a SHA512 digest.
	ECDSAWithSHA512
	// EdDSA on Curve25519 with a SHA512 digest.
	PureEd25519
)

func (s SignatureAlgorithm) String() string

type StoreCertificateChainRequest ¶ added in v0.32.0

type StoreCertificateChainRequest struct {
	Name             string
	CertificateChain []*x509.Certificate
}

StoreCertificateChainRequest is the parameter used in the StoreCertificateChain method of a CertificateChainManager.

type StoreCertificateRequest ¶

type StoreCertificateRequest struct {
	Name        string
	Certificate *x509.Certificate

	// Extractable defines if the new certificate may be exported from the HSM
	// under a wrap key. On pkcs11 sets the CKA_EXTRACTABLE bit.
	//
	// Used by: pkcs11
	Extractable bool
}

StoreCertificateRequest is the parameter used in the StoreCertificate method of a CertificateManager.

type TouchPolicy ¶ added in v0.21.0

type TouchPolicy int

TouchPolicy represents proof-of-presence requirements when signing or decrypting with asymmetric key in a given slot. TouchPolicy is used by the YubiKey KMS.

const (
	TouchPolicyNever TouchPolicy = iota + 1
	TouchPolicyAlways
	TouchPolicyCached
)

type Type ¶

type Type string

Type represents the KMS type used.

const (
	// DefaultKMS is a KMS implementation using software.
	DefaultKMS Type = ""
	// SoftKMS is a KMS implementation using software.
	SoftKMS Type = "softkms"
	// CloudKMS is a KMS implementation using Google's Cloud KMS.
	CloudKMS Type = "cloudkms"
	// AmazonKMS is a KMS implementation using Amazon AWS KMS.
	AmazonKMS Type = "awskms"
	// PKCS11 is a KMS implementation using the PKCS11 standard.
	PKCS11 Type = "pkcs11"
	// YubiKey is a KMS implementation using a YubiKey PIV.
	YubiKey Type = "yubikey"
	// SSHAgentKMS is a KMS implementation using ssh-agent to access keys.
	SSHAgentKMS Type = "sshagentkms"
	// AzureKMS is a KMS implementation using Azure Key Vault.
	AzureKMS Type = "azurekms"
	// CAPIKMS
	CAPIKMS Type = "capi"
	// TPMKMS
	TPMKMS Type = "tpmkms"
	// MacKMS is the KMS implementation using macOS Keychain and Secure Enclave.
	MacKMS Type = "mackms"
)

func TypeOf(rawuri string) (Type, error)

func (t Type) Validate() error