iso7816

README

go-iso7816: Go implementation of the ISO 7816 standard for smart card communication

go-iso7816 implements several helpers and utilities to communicate with ISO7816 compliant smart cards.

This includes:

• Abstract interface for smart card communication

• APDU parsing and serialization

  • Extended-length support
  • TLV en- & decoding variants
    • ASN.1 BER-TLV
    • Simple TLVs
    • Compact TLVs

• Constants of

  • Inter-industry instructions and status codes
  • Application Identifiers (AIDs)

• Basic card management and query support for:

  • YubiKeys
  • Nitrokeys
  • FEITIAN Security Keys

• Card enumeration and filters

• Testing utilities

  • Smartcard Mock Object
  • Tracing Wrapper

In the future we might want to add support for:

• More device support for existing cards
• Global Platform's Secure Channel Protocol (SCP03)
• Cross-platform transport implementations
  • Direct CCID
  • Apples CryptoTokenKit
  • CGo-less pcscd / libpcsc-lite

Contact

Please have a look at the contact page: cunicu.li/docs/contact.

License

go-iso7816 is licensed under the Apache 2.0 license.

Documentation

Index

• Constants
• Variables
• func DecodeResponse(resp []byte) (data []byte, sw1 byte, sw2 byte)
• type CAPDU
  • func (c *CAPDU) Bytes() ([]byte, error)
• type Card
  • func NewCard(c PCSCCard) *Card
  • func (c *Card) If(flt func(card PCSCCard) (bool, error)) (bool, error)
  • func (c *Card) NewTransaction() (*Transaction, error)
  • func (c *Card) Select(aid []byte) (respBuf []byte, err error)
  • func (c *Card) Send(cmd *CAPDU) (respBuf []byte, err error)
• type CardCapabilities
  • func (cc CardCapabilities) DataUnitSize() int
  • func (cc *CardCapabilities) Decode(b []byte) error
  • func (cc CardCapabilities) LogicalChannelCount() int
  • func (cc CardCapabilities) WriteBehaviour() CardCapabilities
• type CardService
  • func (cs CardService) AccessServices() byte
  • func (cs *CardService) Decode(b []byte) error
• type Code
  • func (c Code) Error() string
  • func (c Code) HasMore() bool
  • func (c Code) IsAborted() bool
  • func (c Code) IsCompleted() bool
  • func (c Code) IsSuccess() bool
• type HistoricalBytes
  • func (h *HistoricalBytes) Decode(b []byte) (err error)
• type Instruction
• type MetadataCard
• type PCSCCard
• type RAPDU
  • func ParseRAPDU(b []byte) (*RAPDU, error)
  • func (r *RAPDU) Code() Code
  • func (r *RAPDU) IsError() bool
  • func (r *RAPDU) IsSuccess() bool
  • func (r *RAPDU) IsWarning() bool
• type RID
  • func (r RID) String() string
• type ReaderCard
• type ReconnectableCard
• type Transaction
  • func (tx *Transaction) Close() error
• type Version
  • func ParseVersion(s string) (v Version, err error)
  • func (v Version) Less(w Version) bool
  • func (v Version) String() string

Constants

const (
	LenHeader          = 4 // LenHeader defines the length of the header of an APDU.
	LenLCStandard      = 1 // LenLCStandard defines the length of the LC of a standard length APDU.
	LenLCExtended      = 3 // LenLCExtended defines the length of the LC of an extended length APDU.
	LenResponseTrailer = 2 // LenResponseTrailer defines the length of the trailer of a RAPDU.

	MaxLenCommandDataStandard  = (1 << 8) - 1  // MaxLenCommandDataStandard defines the maximum command data length of a standard length CAPDU.
	MaxLenResponseDataStandard = (1 << 8)      // MaxLenResponseDataStandard defines the maximum response data length of a standard length RAPDU.
	MaxLenCommandDataExtended  = (1 << 16) - 1 // MaxLenCommandDataExtended defines the maximum command data length of an extended length CAPDU.
	MaxLenResponseDataExtended = (1 << 16)     // MaxLenResponseDataExtended defines the maximum response data length of an extended length RAPDU.
)

const (
	// MaxLenCmdDataStandard defines the maximum command data length of a standard length command APDU.
	MaxLenCmdDataStandard = 255

	// MaxLenRespDataStandard defines the maximum response data length of a standard length response APDU.
	MaxLenRespDataStandard = 256

	// MaxLenCmdDataExtended defines the maximum command data length of an extended length command APDU.
	MaxLenCmdDataExtended = 65535

	// MaxLenRespDataExtended defines the maximum response data length of an extended length response APDU.
	MaxLenRespDataExtended = 65536
)

Variables

var (
	// https://www.eftlab.com/knowledge-base/complete-list-of-registered-application-provider-identifiers-rid
	RidNIST           = RID{0xA0, 0x00, 0x00, 0x03, 0x08}
	RidFSFE           = RID{0xD2, 0x76, 0x00, 0x01, 0x24}
	RidYubico         = RID{0xA0, 0x00, 0x00, 0x05, 0x27}
	RidFIDO           = RID{0xA0, 0x00, 0x00, 0x06, 0x47}
	RidSolokeys       = RID{0xA0, 0x00, 0x00, 0x08, 0x47}
	RidGlobalPlatform = RID{0xA0, 0x00, 0x00, 0x01, 0x51}
	RidNXPNFC         = RID{0xD2, 0x76, 0x00, 0x00, 0x85}
)

var (
	// https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-73-4.pdf
	AidPIV = concat(RidNIST[:], 0x00, 0x00, 0x10, 0x00)

	// https://gnupg.org/ftp/specs/OpenPGP-smart-card-application-3.4.1.pdf
	AidOpenPGP = concat(RidFSFE[:], 0x01)

	// https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html#nfc-applet-selection
	AidFIDO = concat(RidFIDO[:], 0x2F, 0x00, 0x01)

	// https://github.com/Yubico/yubikey-manager/blob/6496393f9269e86fb7b4b67907b397db33b50c2d/yubikit/core/smartcard.py#L66
	AidYubicoOTP           = concat(RidYubico[:], 0x20, 0x01)
	AidYubicoManagement    = concat(RidYubico[:], 0x47, 0x11, 0x17)
	AidYubicoOATH          = concat(RidYubico[:], 0x21, 0x01)
	AidYubicoHSMAuth       = concat(RidYubico[:], 0x21, 0x07, 0x01)
	AidSolokeysAdmin       = concat(RidSolokeys[:], 0x00, 0x00, 0x00, 0x01)
	AidSolokeysProvisioner = concat(RidSolokeys[:], 0x01, 0x00, 0x00, 0x01)
	AidCardManager         = concat(RidGlobalPlatform[:], 0x00, 0x00, 0x00)
	AidNDEF                = concat(RidNXPNFC[:], 0x01, 0x01)

	// Feitian seems to use an unregistered RID?
	AidFeitianOTP = []byte{0xD1, 0x56, 0x00, 0x01, 0x32, 0x83, 0x26, 0x01, 0x01}
)

var (
	// General or unspecified warnings & errors
	ErrSuccess                    = Code{0x90, 0x00}
	ErrUnspecifiedWarning         = Code{0x62, 0x00} // No information given (warning)
	ErrUnspecifiedWarningModified = Code{0x63, 0x00} // No information given (warning), on-volatile memory has changed
	ErrUnspecifiedError           = Code{0x64, 0x00} // No information given (error)
	ErrUnspecifiedErrorModified   = Code{0x65, 0x00} // No information given (error), on-volatile memory has changed
	ErrWrongLength                = Code{0x67, 0x00} // Wrong length; no further indication
	ErrUnsupportedFunction        = Code{0x68, 0x00} // Function in CLA not supported
	ErrCommandNotAllowed          = Code{0x69, 0x00} // Command not allowed
	ErrWrongParamsNoInfo          = Code{0x6A, 0x00} // No information given (error)
	ErrWrongParams                = Code{0x6B, 0x00} // Wrong parameters P1-P2
	ErrUnsupportedInstruction     = Code{0x6D, 0x00} // Instruction code not supported or invalid
	ErrUnsupportedClass           = Code{0x6E, 0x00} // Class not supported
	ErrNoDiag                     = Code{0x6F, 0x00} // No precise diagnosis

	// Specific warnings & errors
	ErrResponseMayBeCorrupted              = Code{0x62, 0x81} // Part of returned data may be corrupted
	ErrEOF                                 = Code{0x62, 0x82} // End of file or record reached before reading Ne bytes
	ErrSelectedFileDeactivated             = Code{0x62, 0x83} // Selected file deactivated
	ErrInvalidFileControlInfo              = Code{0x62, 0x84} // File control information not formatted according to 5.3.3
	ErrSelectedFileInTermination           = Code{0x62, 0x85} // Selected file in termination state
	ErrNoSensorData                        = Code{0x62, 0x86} // No input data available from a sensor on the card
	ErrFileFilledUp                        = Code{0x63, 0x81} // File filled up by the last write
	ErrImmediateResponseRequired           = Code{0x64, 0x01} // Immediate response required by the card
	ErrMemory                              = Code{0x65, 0x81} // Memory failure
	ErrLogicalChannelNotSupported          = Code{0x68, 0x81} // Logical channel not supported
	ErrSecureMessagingNotSupported         = Code{0x68, 0x82} // Secure messaging not supported
	ErrExpectedLastCommand                 = Code{0x68, 0x83} // Last command of the chain expected
	ErrCommandChainingNotSupported         = Code{0x68, 0x84} // Command chaining not supported
	ErrCommandIncompatibleWithFile         = Code{0x69, 0x81} // Command incompatible with file structure
	ErrSecurityStatusNotSatisfied          = Code{0x69, 0x82} // Security status not satisfied
	ErrAuthenticationMethodBlocked         = Code{0x69, 0x83} // Authentication method blocked
	ErrReferenceDataNotUsable              = Code{0x69, 0x84} // Reference data not usable
	ErrConditionsOfUseNotSatisfied         = Code{0x69, 0x85} // Conditions of use not satisfied
	ErrCommandNotAllowedNoCurrentEF        = Code{0x69, 0x86} // Command not allowed (no current EF)
	ErrExpectedSecureMessaging             = Code{0x69, 0x87} // Expected secure messaging data objects missing
	ErrIncorrectSecureMessagingDataObjects = Code{0x69, 0x88} // Incorrect secure messaging data objects
	ErrIncorrectData                       = Code{0x6A, 0x80} // Incorrect parameters in the command data field
	ErrFunctionNotSupported                = Code{0x6A, 0x81} // Function not supported
	ErrFileOrAppNotFound                   = Code{0x6A, 0x82} // File or application not found
	ErrRecordNotFound                      = Code{0x6A, 0x83} // Record not found
	ErrNoSpace                             = Code{0x6A, 0x84} // Not enough memory space in the file
	ErrInvalidNcWithTLV                    = Code{0x6A, 0x85} // Nc inconsistent with TLV structure
	ErrIncorrectParams                     = Code{0x6A, 0x86} // Incorrect parameters P1-P2
	ErrInvalidNcWithParams                 = Code{0x6A, 0x87} // Nc inconsistent with parameters P1-P2
	ErrReferenceNotFound                   = Code{0x6A, 0x88} // Referenced data or reference data not found (exact meaning depending on the command)
	ErrFileAlreadyExists                   = Code{0x6A, 0x89} // File already exists
	ErrNameAlreadyExists                   = Code{0x6A, 0x8A} // DF name already exists
)

var ErrInvalidVersion = errors.New("invalid version")

Functions

func DecodeResponse

func DecodeResponse(resp []byte) (data []byte, sw1 byte, sw2 byte)

Types

type CAPDU

type CAPDU struct {
	Cla    byte        // Cla is the class byte.
	Ins    Instruction // Ins is the instruction byte.
	P1, P2 byte        // P1, P2 is the p1, p2 byte.
	Data   []byte      // Data is the data field.
	Ne     int         // Ne is the total number of expected response data byte (not LE encoded).
}

func (*CAPDU) Bytes

func (c *CAPDU) Bytes() ([]byte, error)

type Card

type Card struct {
	PCSCCard

	InsGetRemaining Instruction
}

func NewCard

func NewCard(c PCSCCard) *Card

func (*Card) If

func (c *Card) If(flt func(card PCSCCard) (bool, error)) (bool, error)

If checks that the card meets the provided filter condition.

func (*Card) NewTransaction

func (c *Card) NewTransaction() (*Transaction, error)

func (*Card) Select

func (c *Card) Select(aid []byte) (respBuf []byte, err error)

func (*Card) Send

func (c *Card) Send(cmd *CAPDU) (respBuf []byte, err error)

Send sends a command APDU to the card nolint: unparam

type CardCapabilities

type CardCapabilities uint32

Card capabilities See 8.1.1.2.7 Card capabilities

const (
	// Table 1
	CardCapRecordIdentifier         CardCapabilities = (1 << iota) // Record identifier supported
	CardCapRecordNumber                                            // Record number supported
	CardCapShortEFIdentifier                                       // Short EF identifier supported
	CardCapImplicitDFSelection                                     // Implicit DF selection
	CardCapDFSelectByFileIdentifier                                // DF selection by file identifier
	CardCapDFSelectByPath                                          // DF selection by path
	CardCapDFSelectByPartialDFName                                 // DF selection by partial DF name
	CardCapDFSelectByFullDFName                                    // DF selection by full DF name

	CardCapFirstTagByteValidFF // Value 'FF' is valid for the first byte of BER-TLV tag fields (see 5.2.2.1)

	CardCapEFsTLVStructure // EFs of TLV structure supported

	CardCapLogicalChannelAssignByInterfaceDevice // Logical channel number assignment by the interface device (see 7.1.2)
	CardCapLogicalChannelAssignByCard            // Logical channel number assignment by the card (see 7.1.2)
	CardCapExtendedLengthInfoInEFATR             // Extended Length Information in EF.ATR/ INFO (OpenPGP specific?)
	CardCapExtendedLength                        // Extended Lc and Le fields (see 5.1)
	CardCapCommandChaining                       // Command chaining (see 5.1.1.1)
)

func (CardCapabilities) DataUnitSize

func (cc CardCapabilities) DataUnitSize() int

DataUnitSize returns the data unit size in quartets Note: 2 quartets are one byte!

func (*CardCapabilities) Decode

func (cc *CardCapabilities) Decode(b []byte) error

func (CardCapabilities) LogicalChannelCount

func (cc CardCapabilities) LogicalChannelCount() int

func (CardCapabilities) WriteBehaviour

func (cc CardCapabilities) WriteBehaviour() CardCapabilities

type CardService

type CardService byte

const (
	CardServiceMF                    CardService = (1 << 0) // Card with MF
	CardServiceBERTLVInATR           CardService = (1 << 4) // BER-TLV data objects available in EF.ATR (see 8.2.1.1)
	CardServiceBERTLVInDIR           CardService = (1 << 5) // BER-TLV data objects available in EF.DIR (see 8.2.1.1)
	CardServiceAppSelectionPartialDF CardService = (1 << 6) // Application Selection by partial DF name
	CardServiceAppSelectionFullDF    CardService = (1 << 7) // Application Selection by full DF name (AID)

	// EF.DIR and EF.ATR access services
	// Access via Cardservice.AccessServices()
	CardServiceAccessByGetDataCmd    CardService = (1 << 2) // By the GET DATA command (TLV structure)
	CardServiceAccessByReadRecordCmd CardService = 0        // By the READ RECORD (S) command (record structure)
	CardServiceAccessByReadBinaryCmd CardService = (1 << 3) // By the READ BINARY command (transparent structure)
)

func (CardService) AccessServices

func (cs CardService) AccessServices() byte

func (*CardService) Decode

func (cs *CardService) Decode(b []byte) error

type Code

type Code [2]byte

Code encapsulates (some) response codes from the spec See: ISO 7816-4 Section 5.1.3 Status Bytes

func (Code) Error

func (c Code) Error() string

Error return the encapsulated error string

func (Code) HasMore

func (c Code) HasMore() bool

HasMore indicates more data that needs to be fetched

func (Code) IsAborted

func (c Code) IsAborted() bool

func (Code) IsCompleted

func (c Code) IsCompleted() bool

func (Code) IsSuccess

func (c Code) IsSuccess() bool

IsSuccess indicates that all data has been successfully fetched

type HistoricalBytes

type HistoricalBytes struct {
	CategoryIndicator byte
	LifeCycleStatus   byte // 8.1.1.3 Status indicator
	ProcessingStatus  Code // 8.1.1.3 Status indicator

	CountryCode      []byte           // 8.1.1.2.1 Country or issuer indicator
	IssuerID         []byte           // 8.1.1.2.1 Country or issuer indicator
	AID              []byte           // 8.1.1.2.2 Application identifier
	CardService      CardService      // 8.1.1.2.3 Card service data
	InitialAccess    []byte           // 8.1.1.2.4 Initial access data
	CardIssuer       []byte           // 8.1.1.2.5 Card issuer's data
	PreIssuing       []byte           // 8.1.1.2.6 Pre-issuing data
	CardCapabilities CardCapabilities // 8.1.1.2.7 Card capabilities
}

See: ISO-7816-4 - Section 8.1.1 Historical bytes

func (*HistoricalBytes) Decode

func (h *HistoricalBytes) Decode(b []byte) (err error)

type Instruction

type Instruction byte

const (
	InsDeactivateFile                 Instruction = 0x04 // Part 9
	InsEraseRecord                    Instruction = 0x0C // Section 7.3.8
	InsEraseBinary                    Instruction = 0x0E // Section 7.2.7
	InsEraseBinaryEven                Instruction = 0x0F // Section 7.2.7
	InsPerformSCQLOperation           Instruction = 0x10 // Part 7
	InsPerformTransactionOperation    Instruction = 0x12 // Part 7
	InsPerformUserOperation           Instruction = 0x14 // Part 7
	InsVerify                         Instruction = 0x20 // Section 7.5.6
	InsVerifyOdd                      Instruction = 0x21 // Section 7.5.6
	InsManageSecurityEnvironment      Instruction = 0x22 // Section 7.5.11
	InsChangeReferenceData            Instruction = 0x24 // Section 7.5.7
	InsDisableVerificationRequirement Instruction = 0x26 // Section 7.5.9
	InsEnableVerificationRequirement  Instruction = 0x28 // Section 7.5.8
	InsPerformSecurityOperation       Instruction = 0x2A // Part 8
	InsResetRetryCounter              Instruction = 0x2C // Section 7.5.10
	InsActivateFile                   Instruction = 0x44 // Part 9
	InsGenerateAsymmetricKeyPair      Instruction = 0x46 // Part 8
	InsManageChannel                  Instruction = 0x70 // Section 7.1.2
	InsExternalOrMutualAuthenticate   Instruction = 0x82 // Section 7.5.4
	InsGetChallenge                   Instruction = 0x84 // Section 7.5.3
	InsGeneralAuthenticate            Instruction = 0x87 // Section 7.5.5
	InsInternalAuthenticate           Instruction = 0x88 // Section 7.5.2
	InsSearchBinary                   Instruction = 0xA0 // Section 7.2.6
	InsSearchBinaryOdd                Instruction = 0xA1 // Section 7.2.6
	InsSearchRecord                   Instruction = 0xA2 // Section 7.3.7
	InsSelect                         Instruction = 0xA4 // Section 7.1.1
	InsReadBinary                     Instruction = 0xB0 // Section 7.2.3
	InsReadBinaryOdd                  Instruction = 0xB1 // Section 7.2.3
	InsReadRecord                     Instruction = 0xB3 // Section 7.3.3
	InsGetResponse                    Instruction = 0xC0 // Section 7.6.1
	InsEnvelope                       Instruction = 0xC2 // Section 7.6.2
	InsEnvelopeOdd                    Instruction = 0xC3 // Section 7.6.2
	InsGetData                        Instruction = 0xCA // Section 7.4.2
	InsGetDataOdd                     Instruction = 0xCB // Section 7.4.2
	InsWriteBinary                    Instruction = 0xD0 // Section 7.2.6
	InsWriteBinaryOdd                 Instruction = 0xD1 // Section 7.2.6
	InsWriteRecord                    Instruction = 0xD2 // Section 7.3.4
	InsUpdateBinary                   Instruction = 0xD7 // Section 7.2.5
	InsPutData                        Instruction = 0xDA // Section 7.4.3
	InsPutDataOdd                     Instruction = 0xDB // Section 7.4.3
	InsUpdateRecord                   Instruction = 0xDC // Section 7.3.5
	InsUpdateRecordOdd                Instruction = 0xDD // Section 7.3.5
	InsCreateFile                     Instruction = 0xE0 // Part 9
	InsAppendRecord                   Instruction = 0xE2 // Section 7.3.6
	InsDeleteFile                     Instruction = 0xE4 // Part 9
	InsTerminateDF                    Instruction = 0xE6 // Part 9
	InsTerminateEF                    Instruction = 0xE8 // Part 9
	InsTerminateCardUsage             Instruction = 0xFE // Part 9
)

type MetadataCard

type MetadataCard interface {
	Metadata() map[string]string
}

type PCSCCard

type PCSCCard interface {
	Transmit([]byte) ([]byte, error)
	BeginTransaction() error
	EndTransaction() error
	Close() error
	Base() PCSCCard
}

type RAPDU

type RAPDU struct {
	Data     []byte
	SW1, SW2 byte
}

func ParseRAPDU

func ParseRAPDU(b []byte) (*RAPDU, error)

ParseRAPDU parses a Response APDU and returns a RAPDU.

func (*RAPDU) Code

func (r *RAPDU) Code() Code

func (*RAPDU) IsError

func (r *RAPDU) IsError() bool

IsError returns true if the RAPDU indicates an error during the execution of a command ('0x64xx', '0x65xx' or from '0x67xx' to 0x6Fxx'), otherwise false.

func (*RAPDU) IsSuccess

func (r *RAPDU) IsSuccess() bool

IsSuccess returns true if the RAPDU indicates the successful execution of a command ('0x61xx' or '0x9000'), otherwise false.

func (*RAPDU) IsWarning

func (r *RAPDU) IsWarning() bool

IsWarning returns true if the RAPDU indicates the execution of a command with a warning ('0x62xx' or '0x63xx'), otherwise false.

type RID

type RID [5]byte

func (RID) String

func (r RID) String() string

type ReaderCard

type ReaderCard interface {
	Reader() string
}

type ReconnectableCard

type ReconnectableCard interface {
	Reconnect(reset bool) error
}

type Transaction

type Transaction struct {
	*Card
}

func (*Transaction) Close

func (tx *Transaction) Close() error

type Version

type Version struct {
	Major int
	Minor int
	Patch int
}

Version encodes a major, minor, and patch version.

func ParseVersion

func ParseVersion(s string) (v Version, err error)

func (Version) Less

func (v Version) Less(w Version) bool

func (Version) String

func (v Version) String() string