iso7816

package module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 15, 2024 License: Apache-2.0 Imports: 7 Imported by: 4

README

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

GitHub Workflow Status goreportcard Codecov branch License GitHub go.mod Go version Go Reference

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:

  • 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

View Source 
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.
)
View Source 
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

View Source 
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}
)
View Source 
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}
)
View Source 
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
)
View Source 
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 added in v0.8.0 

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 added in v0.3.0 

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 added in v0.3.0 

func (cc CardCapabilities) DataUnitSize() int

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

func (*CardCapabilities) Decode added in v0.3.0 

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

func (CardCapabilities) LogicalChannelCount added in v0.3.0 

func (cc CardCapabilities) LogicalChannelCount() int

func (CardCapabilities) WriteBehaviour added in v0.3.0 

func (cc CardCapabilities) WriteBehaviour() CardCapabilities

type CardService added in v0.3.0 

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 added in v0.3.0 

func (cs CardService) AccessServices() byte

func (*CardService) Decode added in v0.3.0 

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 added in v0.3.0 

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 added in v0.3.0 

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 added in v0.5.0 

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 added in v0.3.0 

type RID [5]byte

func (RID) String added in v0.3.0 

func (r RID) String() string

type ReaderCard added in v0.8.0 

type ReaderCard interface {
	Reader() string
}

type ReconnectableCard added in v0.6.0 

type ReconnectableCard interface {
	Reconnect(reset bool) error
}

type Transaction 

type Transaction struct {
	*Card
}

func (*Transaction) Close 

func (tx *Transaction) Close() error

type Version added in v0.2.0 

type Version struct {
	Major int
	Minor int
	Patch int
}

Version encodes a major, minor, and patch version.

func ParseVersion added in v0.2.0 

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

func (Version) Less added in v0.2.0 

func (v Version) Less(w Version) bool

func (Version) String added in v0.2.0 

func (v Version) String() string

Source Files

View all Source files

Directories

Path Synopsis
devices
feitian
nitrokey
Package nitrokey implements basic support for getting status and details about Nitrokey 3 tokens.
 Package nitrokey implements basic support for getting status and details about Nitrokey 3 tokens.
yubikey
Package yubikey implements basic support for getting status and details about YubiKey tokens.
 Package yubikey implements basic support for getting status and details about YubiKey tokens.
drivers
pcsc
encoding
tlv
Package tlv implements various version (ASN.1 BER, Simple, Compact) TLV encoding using in ISO 7816-4.
 Package tlv implements various version (ASN.1 BER, Simple, Compact) TLV encoding using in ISO 7816-4.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.