# cryptoflex Module — vsmartcard 2021-04-28 documentation

# cryptoflex Module

class `virtualsmartcard.cards.cryptoflex.``CryptoflexMF`(filedescriptor=56, lifecycle=5, simpletlv_data=None, bertlv_data=None, dfname=None)

  Bases: `virtualsmartcard.SmartcardFilesystem.MF`

  `_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.cards.cryptoflex.``CryptoflexOS`(mf, sam, ins2handler=None, maxle=256)

  Bases: `virtualsmartcard.VirtualSmartcard.Iso7816OS`

  property `SAM`

    secure access module

  `execute`(msg)

    Returns response to the given APDU as string of characters

    Parameters

      msg – the APDU as string of characters

  `formatResult`(ins, le, data, sw)
  `getATR`()

    Returns the ATR of the card as string of characters

  `getResponse`(p1, p2, data)
  static `makeATR`(**args)

    Calculate Answer to Reset (ATR) and returns the bitstring.

    > - directConvention (bool): Whether to use direct convention or

    >     inverse convention.

    > - TAi, TBi, TCi (optional): Value between 0 and 0xff. Interface

    >     Characters (for meaning see ISO 7816-3). Note that if no transmission protocol is given, it is automatically selected with T=max{j-1|TAj in args OR TBj in args OR TCj in args}.

    > - T (optional): Value between 0 and 15. Transmission Protocol.

    >     Note that if T is set, TAi/TBi/TCi for i>T are omitted.

    > - histChars (optional): Bitstring with 0 <= len(histChars) <= 15.

    >     Historical Characters T1 to T15 (for meaning see ISO 7816-4).

    T0, TDi and TCK are automatically calculated.

  static `makeThirdSoftwareFunctionTable`(commandChainging=False, extendedLe=False, assignLogicalChannel=0, maximumChannels=0)

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

  property `mf`

    master file

  `powerDown`()

    Powers down the card

  `powerUp`()

    Powers up the card

  `reset`()

    Performs a warm reset of the card (no power down)

  static `seekable`(ins)

class `virtualsmartcard.cards.cryptoflex.``CryptoflexSAM`(mf=None)

  Bases: `virtualsmartcard.SmartcardSAM.SAM`

  `FSdecrypt`(data)

    Decrypt the given data, using the parameters stored in the SAM. Right now we do not encrypt the data. In memory encryption might or might not be added in a future version.

  `FSencrypt`(data)

    Encrypt the given data, using the parameters stored in the SAM. Right now we do not encrypt the data. In memory encryption might or might not be added in a future version.

  `_get_referenced_key`(p1, p2)

    This method returns the key specified by the p2 parameter. The key may be stored on the cards filesystem.

    Parameters

      - p1 – Specifies the algorithm to use.

      - p2 –

        Specifies a reference to the key to be used for encryption.

        b8 | b7 | b6 | b5 | b4 | b3 | b2 | b1 | Meaning
        --- | --- | --- | --- | --- | --- | --- | --- | ---
        0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | No information is given

        0

        Global reference data(e.g. MF specific key)

        1

        Specific reference data(e.g. DF specific key)

        x

        x

        x

        x

        x

        Number of the secret

        Any other value RFU

  `change_reference_data`(p1, p2, data)

    Change the specified referenced data (e.g. CHV) of the card

  `erase_SE`(SEID)

    Erases a Security Environment stored under SEID from the SAM

  `external_authenticate`(p1, p2, data)

    Authenticate the terminal to the card. Check whether Terminal correctly encrypted the given challenge or not

  `generate_public_key_pair`(p1, p2, data)
  `get_card_number`()
  `get_challenge`(p1, p2, data)

    Generate a random number of maximum 8 Byte and return it.

  `internal_authenticate`(p1, p2, data)

    Authenticate card to terminal. Encrypt the challenge of the terminal to prove key posession

  `manage_security_environment`(p1, p2, data)
  `mutual_authenticate`(p1, p2, mutual_challenge)

    Takes an encrypted challenge in the form ‘Terminal Challenge | Card Challenge | Card number’ and checks it for validity. If the challenge is successful the card encrypts ‘Card Challenge | Terminal challenge’ and returns this value

  `parse_SM_CAPDU`(CAPDU, header_authentication)

    Parse a command APDU protected by Secure Messaging and return the unprotected command APDU

  `perform_security_operation`(p1, p2, data)
  `pezorform_security_operation`(p1, p2, data)

    In the cryptoflex card, this is the verify key command. A key is send to the card in plain text and compared to a key stored in the card. This is used for authentication

    Parameters

      data – Contains the key to be verified

    Returns

      SW[NORMAL] in case of success otherwise SW[WARN_NOINFO63]

  `protect_result`(sw, unprotected_result)

    Protect a plain response APDU by Secure Messaging

  `restore_SE`(SEID)

    Restores a Security Environment from the SAM and replaces the current SE with it.

  `set_MF`(mf)

    Setter function for the internal reference to the Filesystem. The SAM needs a reference to the filesystem in order to store/retrieve keys.

  `set_asym_algorithm`(cipher, keytype)
    Parameters

      - cipher – Public/private key object from used for encryption

      - keytype – Type of the public key (e.g. RSA, DSA)

  `store_SE`(SEID)

    Stores the current Security environment in the secure access module. The SEID is used as a reference to identify the SE.

  `verify`(p1, p2, PIN)

    Authenticate the card user. Check if he entered a valid PIN. If the PIN is invalid decrement retry counter. If retry counter equals zero, block the card until reset with correct PUK

class `virtualsmartcard.cards.cryptoflex.``CryptoflexSE`(MF, SAM)

  Bases: `virtualsmartcard.SEutils.Security_Environment`

  `_set_SE`(p2, data)

    Manipulate the current Security Environment. P2 is the tag of a control reference template, data contains control reference objects

  `compute_cryptographic_checksum`(p1, p2, data)

    Compute a cryptographic checksum (e.g. MAC) for the given data. Algorithm and key are specified in the current SE

  `compute_digital_signature`(p1, p2, data)

    Compute a digital signature for the given data. Algorithm and key are specified in the current SE

    Parameters

      - p1 – Must be 0x9E = Secure Messaging class for digital signatures

      - p2 – Must be one of 0x9A, 0xAC, 0xBC. Indicates what kind of data is included in the data field.

  `decipher`(p1, p2, data)

    Decipher data using key, algorithm, IV and Padding specified by the current Security environment.

    Returns

      raw data (no TLV coding). Padding is not removed!!!

  `encipher`(p1, p2, data)

    Encipher data using key, algorithm, IV and Padding specified by the current Security environment.

    Returns

      raw data (no TLV coding).

  `generate_public_key_pair`(p1, p2, data)

    In the Cryptoflex card this command only supports RSA keys.

    Parameters

      - data – Contains the public exponent used for key generation

      - p1 – The key number. Can be used later to refer to the generated key

      - p2 – Used to specify the key length. The mapping is: 0x40 => 256 Bit, 0x60 => 512 Bit, 0x80 => 1024

  `hash`(p1, p2, data)

    Hash the given data using the algorithm specified by the current Security environment.

    Returns

      raw data (no TLV coding).

  `manage_security_environment`(p1, p2, data)

    This method is used to store, restore or erase Security Environments or to manipulate the various parameters of the current SE. P1 specifies the operation to perform, p2 is either the SEID for the referred SE or the tag of a control reference template

    Parameters

      p1 –

      Bitmask according to this table

      b8 | b7 | b6 | b5 | b4 | b3 | b2 | b1 | Meaning
      --- | --- | --- | --- | --- | --- | --- | --- | ---

      1

      Secure messaging in command data field

      1

      Secure messaging in response data field

      1

      Computation, decipherment, internal authentication and key agreement

      1

      Verification, encipherment, external authentication and key agreement

      0

      0

      0

      1

      SET

      1 | 1 | 1 | 1 | 0 | 0 | 1 | 0 | STORE
      1 | 1 | 1 | 1 | 0 | 0 | 1 | 1 | RESTORE
      1 | 1 | 1 | 1 | 0 | 1 | 0 | 0 | ERASE

  `parse_SM_CAPDU`(CAPDU, authenticate_header)

    This methods parses a data field including Secure Messaging objects. SM_header indicates whether or not the header of the message shall be authenticated. It returns an unprotected command APDU

    Parameters

      - CAPDU – The protected CAPDU to be parsed

      - authenticate_header – Whether or not the header should be included in authentication mechanisms

    Returns

      Unprotected command APDU

  `perform_security_operation`(p1, p2, data)

    In the end this command is nothing but a big switch for all the other commands in ISO 7816-8. It will invoke the appropriate command and return its result

  `protect_response`(sw, result)

    This method protects a response APDU using secure messaging mechanisms

    Returns

      the protected data and the SW bytes

  `verify_certificate`(p1, p2, data)

    Verify a certificate send by the terminal using the internal trust anchors. This method is currently not implemented.

  `verify_cryptographic_checksum`(p1, p2, data)

    Verify the cryptographic checksum contained in the data field. Data field must contain a cryptographic checksum (tag 0x8E) and a plain value (tag 0x80)

  `verify_digital_signature`(p1, p2, data)

    Verify the digital signature contained in the data field. Data must contain a data to sign (tag 0x9A, 0xAC or 0xBC) and a digital signature (0x9E)