goyubikey

README

go-yubikey

Some utils wrap for https://github.com/go-piv/piv-go.

Version	Supported Golang
v1	1.20+

Installation

New Features

// VerifyPIVCerts verify certs exported from yubikey PIV slots by Yubico PIV root ca
func VerifyPIVCerts(certs []*x509.Certificate) error

// ListCards function lists all Yubikey plugin cards.
//
// Note that Yubikey does not allow concurrent access,
// and attempting to do so will result in an error message
// "connecting to smart card: the smart card cannot be accessed
// because of other connections outstanding".
//
// Therefore, it is necessary to make sure that each card is
// properly closed after being used.
func ListCards(skipInvalidCard bool) (cards []*piv.YubiKey, err error)

// InputPassword reads password from stdin input
// and returns it as a string.
func InputPassword(hint string) (string, error)

// Attest function attests the key in the slot by yubico Root CA,
// and returns the certificate of the key.
func Attest(yk *piv.YubiKey, slot piv.Slot) (slotCert *x509.Certificate, err error)

// Decrypt decrypt by slot's private key
func Decrypt(yk *piv.YubiKey,
    pin string,
    slot piv.Slot,
    cipher []byte) (plaintext []byte, err error)

// SignWithSHA256 signs the content using the private key present in the slot
// described by YubiKey.
// It returns the signature or an error in case of any failures.
func SignWithSHA256(yk *piv.YubiKey,
    pin string,
    slot piv.Slot,
    content io.Reader) (signature []byte, err error)


// ResetForPIV will reset card and set PUK/PIN/PIV key
func ResetForPIV(card *piv.YubiKey, pin string, opts ...ResetForPIVOption) (err error)

Documentation

Overview

Package goyubikey utils for yubikey

Index

• func Attest(yk *piv.YubiKey, slot piv.Slot) (slotCert *x509.Certificate, err error)
• func Decrypt(yk *piv.YubiKey, pin string, slot piv.Slot, cipher []byte) (plaintext []byte, err error)
• func InputPassword(hint string) (string, error)
• func ListCards(skipInvalidCard bool) (cards []*piv.YubiKey, err error)
• func NewPIN() (string, error)
• func NewPUK() (string, error)
• func ResetForPIV(card *piv.YubiKey, pin string, opts ...ResetForPIVOption) (err error)
• func SignWithSHA256(yk *piv.YubiKey, pin string, slot piv.Slot, content io.Reader) (signature []byte, err error)
• func VerifyPIVCerts(certs []*x509.Certificate) error
• type ResetForPIVOption
  • func WithRequireTouch() ResetForPIVOption
  • func WithSlot(slot piv.Slot) ResetForPIVOption

Functions

func Attest

func Attest(yk *piv.YubiKey, slot piv.Slot) (slotCert *x509.Certificate, err error)

Attest function attests the key in the slot by yubico Root CA, and returns the certificate of the key.

func Decrypt

func Decrypt(yk *piv.YubiKey,
	pin string,
	slot piv.Slot,
	cipher []byte) (plaintext []byte, err error)

Decrypt decrypt by slot's private key

func InputPassword

func InputPassword(hint string) (string, error)

InputPassword reads password from stdin input and returns it as a string.

func ListCards

func ListCards(skipInvalidCard bool) (cards []*piv.YubiKey, err error)

ListCards function lists all Yubikey plugin cards.

Note that Yubikey does not allow concurrent access, and attempting to do so will result in an error message "connecting to smart card: the smart card cannot be accessed because of other connections outstanding".

Therefore, it is necessary to make sure that each card is properly closed after being used.

func NewPIN

func NewPIN() (string, error)

NewPIN will generate a random PIN

func NewPUK

func NewPUK() (string, error)

NewPUK will generate a random PUK

func ResetForPIV

func ResetForPIV(card *piv.YubiKey, pin string, opts ...ResetForPIVOption) (err error)

ResetForPIV will reset card and set PUK/PIN/PIV key

func SignWithSHA256

func SignWithSHA256(yk *piv.YubiKey,
	pin string,
	slot piv.Slot,
	content io.Reader) (signature []byte, err error)

SignWithSHA256 signs the content using the private key present in the slot described by YubiKey. It returns the signature or an error in case of any failures.

func VerifyPIVCerts

func VerifyPIVCerts(certs []*x509.Certificate) error

VerifyPIVCerts verify certs exported from yubikey PIV slots by Yubico PIV root ca

Types

type ResetForPIVOption

type ResetForPIVOption func(*resetForPIVOption) error

ResetForPIVOption is option for ResetForPIV

func WithRequireTouch

func WithRequireTouch() ResetForPIVOption

WithRequireTouch (optional) set require touch for PIV key

default is false

func WithSlot

func WithSlot(slot piv.Slot) ResetForPIVOption

WithSlot (optional) set slot for PIV key

default is piv.SlotAuthentication