# SEutils Module — vsmartcard 2021-04-28 documentation

# SEutils Module

class `virtualsmartcard.SEutils.``ControlReferenceTemplate`(tag, config='')

  Bases: `object`

  Control Reference Templates are used to configure the Security Environments. They specify which algorithms to use in which mode of operation and with which keys. There are six different types of Control Reference Template: HT, AT, KT, CCT, DST, CT-sym, CT-asym.

  `__replace_tag`(tag, data)

    Adjust the config string using a given tag, value combination. If the config string already contains a tag, value pair for the given tag, replace it. Otherwise append tag, length and value to the config string.

  `__set_algo`(data)

    Set the algorithm to be used by this CRT. The algorithms are specified in a global dictionary. New cards may add or modify this table in order to support new or different algorithms.

    Parameters

      data – reference to an algorithm

  `__set_iv`(tag, length, value)
  `__set_key`(tag, value)
  `parse_SE_config`(config)

    Parse a control reference template as given e.g. in an MSE APDU.

    Parameters

      config – a TLV string containing the configuration for the CRT.

  `to_string`()

    Return the content of the CRT, encoded as TLV data in a string

class `virtualsmartcard.SEutils.``Security_Environment`(MF, SAM)

  Bases: `object`

  `_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)

    The GENERATE PUBLIC-KEY PAIR command either initiates the generation and storing of a key pair, i.e., a public key and a private key, in the card, or accesses a key pair previously generated in the card.

    Parameters

      - p1 – should be 0x00 (generate new key)

      - p2 – ‘00’ (no information provided) or reference of the key to be generated

      - data – One or more CRTs associated to the key generation if P1-P2 different from ‘0000’

  `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)