gopiv

README

gopiv

A NIST 800-73-4 standards compliant PIV library written in Go, with support for additional card management functionality offered by various manufacturers' proprietary extensions to the PIV protocol. Work in progress.

Use

Uses the scard go library to interact with the underlying smartcard.

ctx, err := scard.EstablishContext()
if err != nil {
	log.Fatalln(err)
}

readers, err := ctx.ListReaders()
if err != nil {
	log.Fatalln(err)
}

if len(readers) == 0 {
	log.Fatalln("No connected smartcard readers")
}

card, err := ctx.Connect(readers[0], scard.ShareShared, scard.ProtocolAny)
if err != nil {
	log.Fatalln(err) // No smartcard inserted in reader
}

defer card.Disconnect(scard.ResetCard)

pivCard, err := gopiv.GetPivCard(card)
if err != nil {
	log.Fatalln(err) // Connected smartcard supports PIV
}

cert, err := pivCard.GetCertificate(gopiv.AuthenticationSlot)
if err != nil {
	log.Fatalln(err)
}

log.Println(cert.Subject.CommonName)

if yubikey, ok := pivCard.(*gopiv.Yubikey); ok {
	// Connected smartcard supports Yubico's PIV extensions

	attestation, err := yubikey.Attest(gopiv.AuthenticationKey)
	if err != nil {
		log.Fatalln(err)
	}

	log.Println(cert.Subject.CommonName)
}

Documentation

Index

• Constants
• Variables
• func SetDebug(on bool)
• type GenericPivCard
  • func (p *GenericPivCard) AdminAuthenticate(managementKey []byte) error
  • func (p *GenericPivCard) Authenticate(withKey KeyReference, value string) (*KeyReferenceAuthenticationStatus, error)
  • func (p *GenericPivCard) ChangeAuthenticationData(key KeyReference, currentValue, newValue string) error
  • func (p *GenericPivCard) DeAuthenticate(key KeyReference) error
  • func (p *GenericPivCard) GeneratePrivateKey(key KeyReference, algorithm KeyAlgorithm) (crypto.Signer, error)
  • func (p *GenericPivCard) GetAdminAuthenticationWitness() ([]byte, error)
  • func (p *GenericPivCard) GetApplicationLabel() string
  • func (p *GenericPivCard) GetAuthenticationStatus(forKey KeyReference) (*KeyReferenceAuthenticationStatus, error)
  • func (p *GenericPivCard) GetCertificate(slot Slot) (*x509.Certificate, error)
  • func (p *GenericPivCard) GetSigner(key KeyReference) (crypto.Signer, error)
  • func (p *GenericPivCard) GetSupportedAlgorithms() ([]KeyAlgorithm, error)
  • func (p *GenericPivCard) GetUUID() ([]byte, error)
  • func (p *GenericPivCard) LoadCertificate(slot Slot, cert []byte) error
  • func (p *GenericPivCard) MutuallyAdminAuthenticateWithChallenge(decryptedWitness, challenge []byte) ([]byte, error)
  • func (p *GenericPivCard) UnblockPIN(puk, newPin string) (*KeyReferenceAuthenticationStatus, error)
• type KeyAlgorithm
• type KeyReference
• type KeyReferenceAuthenticationStatus
• type PivCard
  • func GetPivCard(card *scard.Card) (PivCard, error)
• type Slot
• type Yubikey
  • func (y *Yubikey) Attest(key KeyReference) (*x509.Certificate, error)
  • func (y *Yubikey) GetSerialNumber() ([]byte, error)
  • func (y *Yubikey) GetVersion() (string, error)
  • func (y *Yubikey) ResetToDefaults() error
  • func (y *Yubikey) SetManagementKey(newManagementKey []byte) error

Constants

const (
	CardholderPIN         KeyReference = 0x80
	PinUnblockingKey      KeyReference = 0x81
	AuthenticationKey     KeyReference = 0x9A
	ManagementKey         KeyReference = 0x9B
	DigitalSignatureKey   KeyReference = 0x9C
	KeyManagementKey      KeyReference = 0x9D
	CardAuthenticationKey KeyReference = 0x9E

	Rsa2048Key   KeyAlgorithm = 0x07
	EllipticP256 KeyAlgorithm = 0x11
	EllipticP384 KeyAlgorithm = 0x14
	ThreeDesKey  KeyAlgorithm = 0x03
	AesKey       KeyAlgorithm = 0x0C
)

Variables

var (
	YkAttestationSlot Slot         = []byte{0x5F, 0xFF, 0x01}
	YkAttestationKey  KeyReference = 0xF9
)

Functions

func SetDebug

func SetDebug(on bool)

Types

type GenericPivCard

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

func (*GenericPivCard) AdminAuthenticate

func (p *GenericPivCard) AdminAuthenticate(managementKey []byte) error

func (*GenericPivCard) Authenticate

func (p *GenericPivCard) Authenticate(withKey KeyReference, value string) (*KeyReferenceAuthenticationStatus, error)

func (*GenericPivCard) ChangeAuthenticationData

func (p *GenericPivCard) ChangeAuthenticationData(key KeyReference, currentValue, newValue string) error

func (*GenericPivCard) DeAuthenticate

func (p *GenericPivCard) DeAuthenticate(key KeyReference) error

func (*GenericPivCard) GeneratePrivateKey

func (p *GenericPivCard) GeneratePrivateKey(key KeyReference, algorithm KeyAlgorithm) (crypto.Signer, error)

func (*GenericPivCard) GetAdminAuthenticationWitness

func (p *GenericPivCard) GetAdminAuthenticationWitness() ([]byte, error)

func (*GenericPivCard) GetApplicationLabel

func (p *GenericPivCard) GetApplicationLabel() string

func (*GenericPivCard) GetAuthenticationStatus

func (p *GenericPivCard) GetAuthenticationStatus(forKey KeyReference) (*KeyReferenceAuthenticationStatus, error)

func (*GenericPivCard) GetCertificate

func (p *GenericPivCard) GetCertificate(slot Slot) (*x509.Certificate, error)

func (*GenericPivCard) GetSigner

func (p *GenericPivCard) GetSigner(key KeyReference) (crypto.Signer, error)

func (*GenericPivCard) GetSupportedAlgorithms

func (p *GenericPivCard) GetSupportedAlgorithms() ([]KeyAlgorithm, error)

func (*GenericPivCard) GetUUID

func (p *GenericPivCard) GetUUID() ([]byte, error)

func (*GenericPivCard) LoadCertificate

func (p *GenericPivCard) LoadCertificate(slot Slot, cert []byte) error

func (*GenericPivCard) MutuallyAdminAuthenticateWithChallenge

func (p *GenericPivCard) MutuallyAdminAuthenticateWithChallenge(decryptedWitness, challenge []byte) ([]byte, error)

func (*GenericPivCard) UnblockPIN

func (p *GenericPivCard) UnblockPIN(puk, newPin string) (*KeyReferenceAuthenticationStatus, error)

type KeyAlgorithm

type KeyAlgorithm byte

type KeyReference

type KeyReference byte

type KeyReferenceAuthenticationStatus

type KeyReferenceAuthenticationStatus struct {
	Key               KeyReference
	Authenticated     bool
	RemainingAttempts *int
}

type PivCard

type PivCard interface {
	GetApplicationLabel() string
	GetSupportedAlgorithms() ([]KeyAlgorithm, error)
	GetCertificate(slot Slot) (*x509.Certificate, error)
	GetUUID() ([]byte, error)
	Authenticate(withKey KeyReference, value string) (*KeyReferenceAuthenticationStatus, error)
	GetAuthenticationStatus(forKey KeyReference) (*KeyReferenceAuthenticationStatus, error)
	DeAuthenticate(key KeyReference) error
	ChangeAuthenticationData(key KeyReference, currentValue, newValue string) error
	UnblockPIN(puk, newPin string) (*KeyReferenceAuthenticationStatus, error)
	GetAdminAuthenticationWitness() ([]byte, error)
	MutuallyAdminAuthenticateWithChallenge(decryptedWitness, challenge []byte) ([]byte, error)
	AdminAuthenticate(managementKey []byte) error
	GeneratePrivateKey(key KeyReference, algorithm KeyAlgorithm) (crypto.Signer, error)
	LoadCertificate(slot Slot, cert []byte) error
	GetSigner(key KeyReference) (crypto.Signer, error)
}

func GetPivCard

func GetPivCard(card *scard.Card) (PivCard, error)

type Slot

type Slot []byte

var (
	AuthenticationSlot     Slot = []byte{0x5F, 0xC1, 0x05}
	CardAuthenticationSlot Slot = []byte{0x5F, 0xC1, 0x01}
	DigitalSignatureSlot   Slot = []byte{0x5F, 0xC1, 0x0A}
	KeyManagementSlot      Slot = []byte{0x5F, 0xC1, 0x0B}
)

type Yubikey

type Yubikey struct {
	*GenericPivCard
	// contains filtered or unexported fields
}

func (*Yubikey) Attest

func (y *Yubikey) Attest(key KeyReference) (*x509.Certificate, error)

func (*Yubikey) GetSerialNumber

func (y *Yubikey) GetSerialNumber() ([]byte, error)

func (*Yubikey) GetVersion

func (y *Yubikey) GetVersion() (string, error)

func (*Yubikey) ResetToDefaults

func (y *Yubikey) ResetToDefaults() error

func (*Yubikey) SetManagementKey

func (y *Yubikey) SetManagementKey(newManagementKey []byte) error