key

Documentation

Overview

Package key contains functionality for working with versioned Prio keys.

Index

• type Key
  • func FromVersions(primaryVersion Version, otherVersions ...Version) (Key, error)
  • func (k Key) Diff(o Key) string
  • func (k Key) Equal(o Key) bool
  • func (k Key) IsEmpty() bool
  • func (k Key) MarshalJSON() ([]byte, error)
  • func (k Key) Primary() Version
  • func (k Key) Rotate(now time.Time, cfg RotationConfig) (Key, error)
  • func (k *Key) UnmarshalJSON(data []byte) error
  • func (k Key) Versions(f func(Version) error) error
• type Material
  • func P256MaterialFrom(key *ecdsa.PrivateKey) (Material, error)
  • func (m Material) AsPKCS8() (string, error)
  • func (m Material) AsX962Uncompressed() (string, error)
  • func (m Material) Equal(o Material) bool
  • func (m Material) MarshalBinary() ([]byte, error)
  • func (m Material) MarshalText() ([]byte, error)
  • func (m Material) Public() *ecdsa.PublicKey
  • func (m Material) PublicAsCSR(csrFQDN string) (string, error)
  • func (m Material) PublicAsPKIX() (string, error)
  • func (m Material) Type() Type
  • func (m *Material) UnmarshalBinary(data []byte) error
  • func (m *Material) UnmarshalText(data []byte) error
• type RotationConfig
  • func (cfg RotationConfig) Validate() error
• type Type
  • func (t Type) New() (Material, error)
  • func (t Type) String() string
• type Version
  • func (v Version) Equal(o Version) bool

Types

type Key

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

Key represents a cryptographic key. It may be "versioned": there may be multiple pieces of key material, any of which should be considered for use in decryption or signature verification. A single version will be considered "primary": this version will be used for encryption or signing.

func FromVersions

func FromVersions(primaryVersion Version, otherVersions ...Version) (Key, error)

FromVersions creates a new key comprised of the given key versions.

func (Key) Diff

func (k Key) Diff(o Key) string

Diff returns a human-readable string describing the differences from the given `o` key to this key, suitable for logging. Diff returns the empty string if and only if the two keys are equal.

func (Key) Equal

func (k Key) Equal(o Key) bool

Equal returns true if and only if this Key is equal to the given Key.

func (Key) IsEmpty

func (k Key) IsEmpty() bool

IsEmpty returns true if and only if this is the empty key, i.e. the key with no versions.

func (Key) MarshalJSON

func (k Key) MarshalJSON() ([]byte, error)

func (Key) Primary

func (k Key) Primary() Version

Primary returns the primary version of the key. It panics if the key is the empty key.

func (Key) Rotate

func (k Key) Rotate(now time.Time, cfg RotationConfig) (Key, error)

Rotate potentially rotates the key according to the provided rotation config, returning a new key (or the same key, if no rotation is necessary).

Keys are rotated according to the following policy:

• If no key versions exist, or if the youngest key version is older than `create_min_age`, create a new key version.
• While there are more than `delete_min_key_count` keys, and the oldest key version is older than `delete_min_age`, delete the oldest key version.
• Determine the current primary version:
• If there is a key version not younger than `primary_min_age`, select the youngest such key version as primary.
• Otherwise, select the oldest key version as primary.

The returned key is guaranteed to include at least one version.

func (*Key) UnmarshalJSON

func (k *Key) UnmarshalJSON(data []byte) error

func (Key) Versions

func (k Key) Versions(f func(Version) error) error

Versions visits the versions contained within this key in an unspecified order, calling the provided function on each version. If the provided function returns an error, Versions stops visiting versions and returns that error. Otherwise, Versions will never return an error.

type Material

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

Material represents raw key material for an asymmetric cryptographic key, including both the private & public portions. It has functionality related to serialization of the key.

func P256MaterialFrom

func P256MaterialFrom(key *ecdsa.PrivateKey) (Material, error)

P256From returns a new Material of type P256 based on the given P256 private key.

func (Material) AsPKCS8

func (m Material) AsPKCS8() (string, error)

AsPKCS8 returns a base64 encoding of the ASN.1 DER-encoding of the key in PKCS#8 (RFC 5208) format.

func (Material) AsX962Uncompressed

func (m Material) AsX962Uncompressed() (string, error)

AsX962Uncompressed returns a base64 encoding of the X9.62 uncompressed encoding of the public portion of the key, concatenated with the secret "D" scalar.

func (Material) Equal

func (m Material) Equal(o Material) bool

func (Material) MarshalBinary

func (m Material) MarshalBinary() ([]byte, error)

func (Material) MarshalText

func (m Material) MarshalText() ([]byte, error)

func (Material) Public

func (m Material) Public() *ecdsa.PublicKey

Public returns the public key associated with this key material as an ecdsa.PublicKey.

func (Material) PublicAsCSR

func (m Material) PublicAsCSR(csrFQDN string) (string, error)

PublicAsCSR returns a PEM-encoding of the ASN.1 DER-encoding of a PKCS#10 (RFC 2986) CSR over the public portion of the key, signed using the private portion of the key, using the provided FQDN as the common name for the request.

func (Material) PublicAsPKIX

func (m Material) PublicAsPKIX() (string, error)

PublicAsPKIX returns a PEM-encoding of the ASN.1 DER-encoding of the public portion of the key in PKIX (RFC 5280) format.

func (Material) Type

func (m Material) Type() Type

Type returns the type of the key material.

func (*Material) UnmarshalBinary

func (m *Material) UnmarshalBinary(data []byte) error

func (*Material) UnmarshalText

func (m *Material) UnmarshalText(data []byte) error

type RotationConfig

type RotationConfig struct {
	CreateKeyFunc func() (Material, error) // CreateKeyFunc returns newly-generated key material, or an error if it can't.
	CreateMinAge  time.Duration            // CreateMinAge is the minimum age of the youngest key version before a new key version will be created.

	PrimaryMinAge time.Duration // PrimaryMinAge is the minimum age of a key version before it may normally be considered "primary".

	DeleteMinAge      time.Duration // DeleteMinAge is the minimum age of a key version before it will be considered for deletion.
	DeleteMinKeyCount int           // DeleteMinKeyCount is the minimum number of key versions before any key versions will be considered for deletion.
}

RotationConfig defines the configuration for a key-rotation operation.

func (RotationConfig) Validate

func (cfg RotationConfig) Validate() error

Validate validates the rotation config, returning an error if and only if there is some problem with the specified configuration parameters.

type Type

type Type uint8

Type represents the kind of key represented by a key.Material.

const (
	// P256 represents an ECDSA P-256 key.
	P256 Type = 1 + iota
)

func (Type) New

func (t Type) New() (Material, error)

New creates a new, randomly-initialized key.

func (Type) String

func (t Type) String() string

type Version

type Version struct {
	KeyMaterial       Material
	CreationTimestamp int64 // Unix seconds timestamp
}

Version represents a single version of a key, i.e. raw private key material, as well as associated metadata. Typically, a Version will be embedded within a Key.

func (Version) Equal

func (v Version) Equal(o Version) bool

Equal returns true if and only if this Version is equal to the given Version.