SmartcardFilesystem Module

class virtualsmartcard.SmartcardFilesystem.DF(parent, fid, filedescriptor=56, lifecycle=5, simpletlv_data=None, bertlv_data=None, dfname=None, data=b'')

Bases: virtualsmartcard.SmartcardFilesystem.File

Class for a dedicated file

append(file)

Appends ‘file’ to the content of the DF.

appendrecord(*argz, **args)

Only a template, will raise an error.

property bertlv_data

list of (tag, length, value)-tuples of BER-TLV coded data objects (encrypted)

property content

list of files of the DF

property data

unknown

decrypt(path, data)

property dfname

string with up to 16 bytes. DF name,which can also be used as applicationidentifier.

encrypt(path, data)

erasebinary(*argz, **args)

Only a template, will raise an error.

property fid

file identifier

property filedescriptor

file descriptor byte

getMF()

Return MF of the card that contains this file

getdata(isSimpleTlv, requestedTL)

Returns a string of either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘requestedTL’ is a list of (tag, length)-tuples that specify which tags should be returned in what size.

getpath()

Returns the path to this file beginning with the MF’s fid.

property lifecycle

life cycle byte

property parent

parent DF

putdata(isSimpleTlv, newtlvlist)

Sets either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘newtlvlist’ is a list of (tag, length, value)-tuples of new data.

readbinary(*argz, **args)

Only a template, will raise an error.

readrecord(*argz, **args)

Only a template, will raise an error.

remove(file)

Removes ‘file’ from the content of the DF

select(attribute, value, reference=0, index_current=0)

Returns the first file of the DF, that has the ‘attribute’ with the specified ‘value’. For partial DF name selection you must specify the first/last/next or previous occurence with ‘reference’ and the index of the current file ‘index_current’ (-1 for None).

property simpletlv_data

list of (tag, length, value)-tuples of SIMPLE-TLV coded data objects (encrypted)

updatebinary(*argz, **args)

Only a template, will raise an error.

updaterecord(*argz, **args)

Only a template, will raise an error.

writebinary(*argz, **args)

Only a template, will raise an error.

writerecord(*argz, **args)

Only a template, will raise an error.

class virtualsmartcard.SmartcardFilesystem.EF(parent, fid, filedescriptor, lifecycle=5, simpletlv_data=None, bertlv_data=None, datacoding=0, shortfid=0)

Bases: virtualsmartcard.SmartcardFilesystem.File

Template class for an elementary file.

appendrecord(*argz, **args)

Only a template, will raise an error.

property bertlv_data

list of (tag, length, value)-tuples of BER-TLV coded data objects (encrypted)

property datacoding

integer. Data coding byte.

decrypt(path, data)

encrypt(path, data)

erasebinary(*argz, **args)

Only a template, will raise an error.

property fid

file identifier

property filedescriptor

file descriptor byte

getMF()

Return MF of the card that contains this file

getdata(isSimpleTlv, requestedTL)

Returns a string of either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘requestedTL’ is a list of (tag, length)-tuples that specify which tags should be returned in what size.

getpath()

Returns the path to this file beginning with the MF’s fid.

property lifecycle

life cycle byte

property parent

parent DF

putdata(isSimpleTlv, newtlvlist)

Sets either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘newtlvlist’ is a list of (tag, length, value)-tuples of new data.

readbinary(*argz, **args)

Only a template, will raise an error.

readrecord(*argz, **args)

Only a template, will raise an error.

select(*argz, **args)

Only a template, will raise an error.

property shortfid

integer with 1<=shortfid<=30.Short EF identifier.

property simpletlv_data

list of (tag, length, value)-tuples of SIMPLE-TLV coded data objects (encrypted)

updatebinary(*argz, **args)

Only a template, will raise an error.

updaterecord(*argz, **args)

Only a template, will raise an error.

writebinary(*argz, **args)

Only a template, will raise an error.

writerecord(*argz, **args)

Only a template, will raise an error.

class virtualsmartcard.SmartcardFilesystem.File(parent, fid, filedescriptor, lifecycle=5, simpletlv_data=None, bertlv_data=None, SAM=None, extra_fci_data=b'')

Bases: object

Template class for a smartcard file.

appendrecord(*argz, **args)

Only a template, will raise an error.

property bertlv_data

list of (tag, length, value)-tuples of BER-TLV coded data objects (encrypted)

decrypt(path, data)

encrypt(path, data)

erasebinary(*argz, **args)

Only a template, will raise an error.

property fid

file identifier

property filedescriptor

file descriptor byte

getMF()

Return MF of the card that contains this file

getdata(isSimpleTlv, requestedTL)

Returns a string of either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘requestedTL’ is a list of (tag, length)-tuples that specify which tags should be returned in what size.

getpath()

Returns the path to this file beginning with the MF’s fid.

property lifecycle

life cycle byte

property parent

parent DF

putdata(isSimpleTlv, newtlvlist)

Sets either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘newtlvlist’ is a list of (tag, length, value)-tuples of new data.

readbinary(*argz, **args)

Only a template, will raise an error.

readrecord(*argz, **args)

Only a template, will raise an error.

select(*argz, **args)

Only a template, will raise an error.

property simpletlv_data

list of (tag, length, value)-tuples of SIMPLE-TLV coded data objects (encrypted)

updatebinary(*argz, **args)

Only a template, will raise an error.

updaterecord(*argz, **args)

Only a template, will raise an error.

writebinary(*argz, **args)

Only a template, will raise an error.

writerecord(*argz, **args)

Only a template, will raise an error.

class virtualsmartcard.SmartcardFilesystem.MF(filedescriptor=56, lifecycle=5, simpletlv_data=None, bertlv_data=None, dfname=None)

Bases: virtualsmartcard.SmartcardFilesystem.DF

Class for a master file

_selectFile(p1, p2, data)

Returns the file specified by ‘p1’ and ‘data’ from the select file command APDU.

append(file)

Appends ‘file’ to the content of the DF.

appendRecord(p1, p2, data)

Function for instruction 0xe2. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

appendrecord(*argz, **args)

Only a template, will raise an error.

property bertlv_data

list of (tag, length, value)-tuples of BER-TLV coded data objects (encrypted)

property content

list of files of the DF

static create(p1, p2, data)

Creates and returns a list of files according to the parameters of a create file command.

createFile(p1, p2, data)

Function for instruction 0xe0. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

property current

the currently selected file

currentDF()

Returns the current DF.

currentEF()

Returns the current EF or None if not available.

property data

unknown

dataObjectHandlingDecodeEncapsulated(p1, p2, data)

Decodes ‘p1’, ‘p2’ and ‘data’ from a data object handling command (i. e. get/put data) with odd instruction code.

Returns

the specified file, True if the following list regards SIMPLE-TLV data objects False otherwise and a list of (tag, length, value)-tuples.

dataObjectHandlingDecodePlain(p1, p2, data)

Decodes ‘p1’, ‘p2’ and ‘data’ from a data object handling command (i. e. get/put data) with even instruction code.

Returns

the specified file, True if the following list regards SIMPLE-TLV data objects False otherwise and a list of (tag, length, value)-tuples.

dataUnitsDecodeEncapsulated(p1, p2, data)

Decodes ‘p1’, ‘p2’ and ‘data’ from a data unit command (i. e. read/write/update/search/erase binary) with odd instruction code.

:returns the specified TransparentStructureEF, a list of offsets and a

list of data strings.

dataUnitsDecodePlain(p1, p2, data)

Decodes ‘p1’, ‘p2’ and ‘data’ from a data unit command (i. e. read/write/update/search/erase binary) with even instruction code.

Returns

the specified TransparentStructureEF, a list of offsets and a list of data strings.

decrypt(path, data)

deleteFile(p1, p2, data)

Function for instruction 0xe4. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

property dfname

string with up to 16 bytes. DF name,which can also be used as applicationidentifier.

static encodeFileControlParameter(file)

Returns a string of TLV-coded file control information of ‘file’. Note: The result is not prepended with tag and length for neither TCP, FMD nor FCI template.

encrypt(path, data)

eraseBinaryEncapsulated(p1, p2, data)

Function for instruction 0x0f. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

eraseBinaryPlain(p1, p2, data)

Function for instruction 0x0e. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

eraseRecord(p1, p2, data)

Function for instruction 0x0c. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

erasebinary(*argz, **args)

Only a template, will raise an error.

property fid

file identifier

property filedescriptor

file descriptor byte

property firstSFT

string of length 1. The firstsoftware function table from thehistorical bytes.

getDataEncapsulated(p1, p2, data)

Function for instruction 0xcb. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

getDataPlain(p1, p2, data)

Function for instruction 0xca. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

getMF()

Return MF of the card that contains this file

getdata(isSimpleTlv, requestedTL)

Returns a string of either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘requestedTL’ is a list of (tag, length)-tuples that specify which tags should be returned in what size.

getpath()

Returns the path to this file beginning with the MF’s fid.

property lifecycle

life cycle byte

static makeFirstSoftwareFunctionTable(DFSelectionByFullDFName=True, DFSelectionByPartialDFName=True, DFSelectionByPath=True, DFSelectionByFID=True, DFSelectionByApplication_implicite=True, ShortFIDSupported=True, RecordNumberSupported=True, RecordIdentifierSupported=True)

Returns a byte according to the first software function table from the historical bytes of the card capabilities.

static makeSecondSoftwareFunctionTable(DCB=1)

The second software function table from the historical bytes contains the data coding byte.

property named_dfs

list of DFs with dfname specified

property parent

parent DF

putDataEncapsulated(p1, p2, data)

Function for instruction 0xdb. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

putDataPlain(p1, p2, data)

Function for instruction 0xda. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

putdata(isSimpleTlv, newtlvlist)

Sets either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘newtlvlist’ is a list of (tag, length, value)-tuples of new data.

readBinaryEncapsulated(p1, p2, data)

Function for instruction 0xb1. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

readBinaryPlain(p1, p2, data)

Function for instruction 0xb0. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

readRecordEncapsulated(p1, p2, data)

Function for instruction 0xb3. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

readRecordPlain(p1, p2, data)

Function for instruction 0xb2. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

readbinary(*argz, **args)

Only a template, will raise an error.

readrecord(*argz, **args)

Only a template, will raise an error.

recordHandlingDecode(p1, p2)

Decodes ‘p1’ and ‘p2’ from a record handling command (i. e. read/write/update/append/search/erase record).

Returns

the specified RecordStructureEF, the number or identifier of the record and a reference, that specifies which record to select (i. e. the last 3 bits of ‘p1’).

remove(file)

Removes ‘file’ from the content of the DF

searchBinaryEncapsulated(p1, p2, data)

searchBinaryPlain(p1, p2, data)

property secondSFT

string of length 1. The secondsoftware function table from thehistorical bytes.

select(attribute, value, reference=0, index_current=0)

Returns the first file of the DF, that has the ‘attribute’ with the specified ‘value’. For partial DF name selection you must specify the first/last/next or previous occurence with ‘reference’ and the index of the current file ‘index_current’ (-1 for None).

selectFile(p1, p2, data)

Function for instruction 0xa4. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

property simpletlv_data

list of (tag, length, value)-tuples of SIMPLE-TLV coded data objects (encrypted)

updateBinaryEncapsulated(p1, p2, data)

Function for instruction 0xd7. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

updateBinaryPlain(p1, p2, data)

Function for instruction 0xd6. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

updateRecordEncapsulated(p1, p2, data)

Function for instruction 0xdd. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

updateRecordPlain(p1, p2, data)

Function for instruction 0xdc. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

updatebinary(*argz, **args)

Only a template, will raise an error.

updaterecord(*argz, **args)

Only a template, will raise an error.

writeBinaryEncapsulated(p1, p2, data)

Function for instruction 0xd1. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string. Returns the status bytes as two byte long integer and the response data as binary string.

writeBinaryPlain(p1, p2, data)

Function for instruction 0xd0. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

writeRecord(p1, p2, data)

Function for instruction 0xd2. Takes the parameter bytes ‘p1’, ‘p2’ as integers and ‘data’ as binary string.

Returns

the status bytes as two byte long integer and the response data as binary string.

writebinary(*argz, **args)

Only a template, will raise an error.

writerecord(*argz, **args)

Only a template, will raise an error.

class virtualsmartcard.SmartcardFilesystem.Record(identifier=None, data=b'')

Bases: object

property data

string. The record’s data.

property identifier

Class for a Record of an elementary of record structure

class virtualsmartcard.SmartcardFilesystem.RecordStructureEF(parent, fid, filedescriptor, lifecycle=5, simpletlv_data=None, bertlv_data=None, datacoding=0, shortfid=0, maxrecordsize=65535, records=[])

Bases: virtualsmartcard.SmartcardFilesystem.EF

Class for an elementary file with record structure.

__getRecords(num_id, reference)

Returns a list of records.

Parameters

• num_id – The requested record’s number or identifier

• reference – Specifies which record to select (usually the last 3 bits of ‘p1’ of a record handling command)

__getRecordsByIdentifier(id, reference)

Returns a list of records and sets the recordpointer to the first record, that matched. Is to be involved by __getRecords.

Parameters

• id – The requested record’s identifier

• reference – Specifies which record to select (usually the last 3 bits of ‘p1’ of a record handling command)

__getRecordsByNumber(number, reference)

Returns a list of records. Is to be involved by __getRecords.

Parameters

• number – The requested record’s number

• reference – Specifies which record to select (usually the last 3 bits of ‘p1’ of a record handling command)

appendrecord(data)

Appends a new record to the file, initializing it with the given data string. Sets the recordpointer to the newly created record.

property bertlv_data

list of (tag, length, value)-tuples of BER-TLV coded data objects (encrypted)

property datacoding

integer. Data coding byte.

decrypt(path, data)

encrypt(path, data)

erasebinary(*argz, **args)

Only a template, will raise an error.

eraserecord(num_id, reference)

Removes a record from the file. ‘num_id’ and ‘reference’ specify the record (see __getRecords).

property fid

file identifier

property filedescriptor

file descriptor byte

getMF()

Return MF of the card that contains this file

getdata(isSimpleTlv, requestedTL)

Returns a string of either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘requestedTL’ is a list of (tag, length)-tuples that specify which tags should be returned in what size.

getpath()

Returns the path to this file beginning with the MF’s fid.

hasFixedRecordSize()

Returns True if the records are of fixed size, False otherwise.

hasSimpleTlv()

Returns True if the EF is of TLV structure, False otherwise.

isCyclic()

Returns True if the EF is of cyclic structure, False otherwise.

property lifecycle

life cycle byte

property maxrecordsize

integer. maximum length of a record’s data.

property parent

parent DF

putdata(isSimpleTlv, newtlvlist)

Sets either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘newtlvlist’ is a list of (tag, length, value)-tuples of new data.

readbinary(*argz, **args)

Only a template, will raise an error.

readrecord(offset, num_id, reference)

Returns a data string from the given ‘offset’. ‘num_id’ and ‘reference’ specify the record (see __getRecords).

property recordpointer

integer. Points to the current record (i. e. index of records).

property records

list of records (encrypted)

resetRecordPointer()

Resets the record pointer.

select(*argz, **args)

Only a template, will raise an error.

property shortfid

integer with 1<=shortfid<=30.Short EF identifier.

property simpletlv_data

list of (tag, length, value)-tuples of SIMPLE-TLV coded data objects (encrypted)

updatebinary(*argz, **args)

Only a template, will raise an error.

updaterecord(num_id, reference, offset, data)

x.updaterecord(num_id, reference, offset, data) <==> x.writerecord(num_id, reference, offset, data, DCB[“ONETIMEWRITE”])

writebinary(*argz, **args)

Only a template, will raise an error.

writerecord(num_id, reference, offset, data, datacoding=None)

Writes a data string to the ‘offset’ of a record using the given data coding byte. ‘num_id’ and ‘reference’ specify the record (see __getRecords).

class virtualsmartcard.SmartcardFilesystem.TransparentStructureEF(parent, fid, filedescriptor=1, lifecycle=5, simpletlv_data=None, bertlv_data=None, datacoding=0, shortfid=0, data=b'')

Bases: virtualsmartcard.SmartcardFilesystem.EF

Class for an elementary file with transparent structure.

appendrecord(*argz, **args)

Only a template, will raise an error.

property bertlv_data

list of (tag, length, value)-tuples of BER-TLV coded data objects (encrypted)

property data

string (encrypted). The file’s data.

property datacoding

integer. Data coding byte.

decrypt(path, data)

encrypt(path, data)

erasebinary(erasefrom, eraseto)

Sets (part of) the content of an EF to its logical erased state, sequentially starting from ‘erasefrom’ ending at ‘eraseto’.

property fid

file identifier

property filedescriptor

file descriptor byte

getMF()

Return MF of the card that contains this file

getdata(isSimpleTlv, requestedTL)

Returns a string of either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘requestedTL’ is a list of (tag, length)-tuples that specify which tags should be returned in what size.

getpath()

Returns the path to this file beginning with the MF’s fid.

property lifecycle

life cycle byte

property parent

parent DF

putdata(isSimpleTlv, newtlvlist)

Sets either the file’s BER-TLV or the file’s SIMPLE-TLV coded data objects depending on the bool ‘isSimpleTlv’. ‘newtlvlist’ is a list of (tag, length, value)-tuples of new data.

readbinary(offset)

Returns the string of decrypted data beginning at ‘offset’.

readrecord(*argz, **args)

Only a template, will raise an error.

select(*argz, **args)

Only a template, will raise an error.

property shortfid

integer with 1<=shortfid<=30.Short EF identifier.

property simpletlv_data

list of (tag, length, value)-tuples of SIMPLE-TLV coded data objects (encrypted)

updatebinary(offsets, datalist)

x.updatebinary(offsets, datalist) <==> x.writebinary(offsets, datalist, DCB[“ONETIMEWRITE”])

updaterecord(*argz, **args)

Only a template, will raise an error.

writebinary(offsets, datalist, datacoding=None)

Writes pieces of data to the specified offsets honoring the given coding byte.

Parameters

• offsets – list of integers. Offsets.

• datalist – list of strings. Data pieces.

• datacoding – the data coding byte to use for writing

writerecord(*argz, **args)

Only a template, will raise an error.

virtualsmartcard.SmartcardFilesystem.get_indexes(items, reference=0, index_current=0)

Returns all indexes of the list, which are specified by ‘reference’ and by the current index ‘index_current’ (-1 for no current item) in the correct order. I. e.:

REF[“IDENTIFIER_FIRST”]: all indexes from first to the last item REF[“IDENTIFIER_LAST”]: all indexes from the last to first item REF[“IDENTIFIER_NEXT”]: all indexes from the next to the last item REF[“IDENTIFIER_PREVIOUS”]: all indexes from the previous to the first item

virtualsmartcard.SmartcardFilesystem.getfile_byrefdataobj(mf, refdataobjs)

Returns a list of files according to the given list of reference data objects.

param mf: the MF param refdataobjs: a list of 3-tuples (tag, length, newvalue)

virtualsmartcard.SmartcardFilesystem.isEqual(list)

Returns True, if all items are equal, otherwise False

virtualsmartcard.SmartcardFilesystem.make_property(prop, doc)

Assigns a property to the calling object. This is used to decorate instance variables with docstrings.

virtualsmartcard.SmartcardFilesystem.prettyprint_anything(indent, thing)

Returns a recursively generated string representation of an object and its attributes.

virtualsmartcard.SmartcardFilesystem.walk(start, path)

Walks a path of fids and returns the last file (EF or DF).

Parameters

• start – DF, where to look for the first fid

• path – a string of fids

virtualsmartcard.SmartcardFilesystem.write(old, newlist, offsets, datacoding, maxsize=None)

Returns the status bytes and the result of a write operation according to the given data coding.

Parameters

• old – string of old data

• newlist – a list of new data string

• offsets – a list of offsets, each for one new data strings

• datacoding – DCB[“ONETIMEWRITE”] (replace) or DCB[“WRITEOR”] (logical or) or DCB[“WRITEAND”] (logical and) or DCB[“PROPRIETARY”] (logical xor)

• maxsize – the maximum number of bytes in the result