pgp

Documentation

Index

• Constants
• type Attestation
  • func ParseAttestation(attestCert *x509.Certificate) (*Attestation, error)
  • func VerifyAttestation(req VerificationRequest) (*Attestation, error)
• type Formfactor
  • func (f Formfactor) MarshalJSON() ([]byte, error)
  • func (f Formfactor) String() string
• type Keysource
  • func (k Keysource) MarshalJSON() ([]byte, error)
  • func (k Keysource) String() string
• type Policy
• type Slot
• type TouchPolicy
  • func (t TouchPolicy) MarshalJSON() ([]byte, error)
  • func (t TouchPolicy) String() string
• type VerificationErrors
  • func (ve VerificationErrors) Error() string
• type VerificationRequest
• type Version

Constants

const (
	SlotSignature    = Slot("SIG")
	SlotEncrypt      = Slot("ENC")
	SlotAuthenticate = Slot("AUT")
)

Types

type Attestation

type Attestation struct {
	// Cardholder is the name of the cardholder
	Cardholder string

	// Keysource
	Keysource Keysource

	// Slot is the key slot
	Slot Slot

	// Version of the YubiKey's firmware.
	Version Version

	// Fingerprint
	Fingerprint string

	// GenerationDate
	GenerationDate time.Time

	// SignatureCounter (if applicable)
	SignatureCounter uint32

	// Serial is the YubiKey's serial number.
	Serial uint32

	// Formfactor indicates the physical type of the YubiKey.
	//
	// Formfactor may be empty Formfactor(0) for some YubiKeys.
	Formfactor Formfactor

	// TouchPolicy set on the slot.
	TouchPolicy TouchPolicy
}

Attestation contains additional information about a key attested to be on a card.

func ParseAttestation

func ParseAttestation(attestCert *x509.Certificate) (*Attestation, error)

ParseAttestation parses a YubiKey OPGP attestation certificate and returns an Attestation.

func VerifyAttestation

func VerifyAttestation(req VerificationRequest) (*Attestation, error)

VerifyAttestation verifies the signature chain of an attestation cert and evaluates the attributes in the attestation against a list of policies. If the cert chain is valid and all policy rules apply nil is returned. Otherwise an error that may be cast to .(VerificationErrors) will be returned. This accumulator contains a slice of one or more errors representing policy violations.

type Formfactor

type Formfactor int

Formfactor enumerates the physical set of forms a key can take. USB-A vs. USB-C and Keychain vs. Nano.

const (
	FormfactorUnspecified Formfactor = iota
	FormfactorUSBAKeychain
	FormfactorUSBANano
	FormfactorUSBCKeychain
	FormfactorUSBCNano
	FormfactorUSBCLightningKeychain
)

Formfactors recognized by this package.

func (Formfactor) MarshalJSON

func (f Formfactor) MarshalJSON() ([]byte, error)

MarshalJSON encodes value into String().

func (Formfactor) String

func (f Formfactor) String() string

type Keysource

type Keysource int

Keysourxe represents the source of the key (imported or generated)

const (
	KeysourceImported Keysource = iota
	KeysourceGenerated
)

func (Keysource) MarshalJSON

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

MarshalJSON encodes value into String().

func (Keysource) String

func (k Keysource) String() string

type Policy

type Policy struct {
	AllowedTouchPolicies []TouchPolicy
	AllowedKeySources    []Keysource
	AllowedSlots         []Slot
	AllowedCardholders   []string
}

Policy represents a set of allowed contents of a YubiKey OPGP attestation certificate.

type Slot

type Slot string

Slot represents the YubiKey card slot that is covered by the attestation.

type TouchPolicy

type TouchPolicy int

TouchPolicy represents proof-of-presence requirements when signing or decrypting with asymmetric key in a given slot.

const (
	TouchPolicyDisabled        TouchPolicy = iota // No touch required
	TouchPolicyEnabled                            // Touch required
	TouchPolicyPermanent                          // Touch required, can't be disabled without a full reset
	TouchPolicyCached                             // Touch required, cached for 15s after use
	TouchPolicyPermanentCached                    // Touch required, cached for 15s after use, can't be disabled without a full reset
)

Touch policies supported by this package.

$ ykman openpgp set-touch

func (TouchPolicy) MarshalJSON

func (t TouchPolicy) MarshalJSON() ([]byte, error)

MarshalJSON encodes value into String().

func (TouchPolicy) String

func (t TouchPolicy) String() string

type VerificationErrors

type VerificationErrors []error

VerificationErrors holds errors representing policy violations from a verification request.

func (VerificationErrors) Error

func (ve VerificationErrors) Error() string

Error implements the error interface for VerificationErrors and returns a summary of the error messages. To inspect the list of errors individually you would cast the err to VerificationError and inspect the list.

errs := err.(VerificationErrors)

type VerificationRequest

type VerificationRequest struct {
	AttestCert       *x509.Certificate
	AttestSignerCert *x509.Certificate
	Policy           Policy
}

VerificationRequest contains a Yubikey Attestation certificate signed by a attestation signer key.

Attestation (AttestCert) certs can be generated with the `ykman` utility and the `ykman openpgp attest` command. The AttestSignerCert used to sign the attestation cert (signer) can be exported from the Yubikey using the `ykman openpgp export-certificate ATT`:

# create an attestation cert covering the key in the authentication (AUT) key slot
 ykman openpgp attest AUT attest.pem

# export the attestation (ATT) singer cert used to sign the cert above.
ykman openpgp attest AUT signer.pem

type Version

type Version struct {
	Major int
	Minor int
	Patch int
}

Version encodes a major, minor, and patch version.