SecureMessaging

internal final class SecureMessaging

A class responsible for protecting APDU commands sent and unprotecting APDU responses received during a secure session in NFC communication.

The SecureMessaging class is in charge of safeguarding the confidentiality and integrity of APDU commands and responses exchanged in a NFCSecureSession. It employs either 3DES or AES in encrypt-then-authenticate mode, ensuring the data is padded, encrypted, and authenticated.

Session Initiation

Secure Messaging is initiated when a secure session is established. Session keys are derived using a key derivation function (KDF), and the data is padded, encrypted, and authenticated in this mode.

Session Termination

Secure Messaging is terminated if a Secure Messaging error occurs or a plain APDU is received. In such cases, the stored session keys are deleted, and the terminal’s access rights are reset.

3DES Modes of Operation

  • Encryption: Two-key 3DES in CBC mode with a zero IV, using padding method 2.

  • Message Authentication: Cryptographic checksums are calculated using MAC algorithm 3 with block cipher DES, zero IV, and padding method 2. The MAC length must be 8 bytes.

  • Send Sequence Counter (SSC): For Secure Messaging following Basic Access Control (BAC), the SSC is initialized by concatenating the four least significant bytes of RND.IC and RND.IFD. In all other cases, the SSC is initialized to zero.

AES Modes of Operation

  • Encryption: AES in CBC mode with a specific IV.
  • Message Authentication: AES in CMAC mode with a MAC length of 8 bytes.

  • Send Sequence Counter (SSC): The SSC is initialized to zero.

See also

NFCSecureSession, SecurityConfiguration SecureChannel and SessionKeyGenerator

  • Declaration

    Swift

    internal init(secureChannel: SecureChannel, securityConfig: SecurityConfiguration)

  • Protects an APDU command during a secure session.

    To protect an APDU command, the SecureMessaging class performs the following actions:

    1. Masks and pads the Command Header (CLA|INS|P1|P2). The class byte (CLA) is replaced with 0x0C.
    2. Pads and encrypts the data with the session key KSenc.
    3. Builds the Data Object DO'87’.
    4. Builds the Data Object DO'97’.
    5. Computes the concatenation M = CmdHeader || DO'87’ || DO'97’.
    6. Increments the session SSC and computes the MAC over N = SSC || M (padded) with the session key KSmac.
    7. Builds the Data Object DO'8E’.
    8. Constructs the protected APDU and returns it.

    Declaration

    Swift

    internal func protect(apdu: NFCISO7816APDU) throws -> NFCISO7816APDU

    Parameters

    apdu

    The APDU command to be protected.

    Return Value

    The protected APDU command.

  • Unwraps an APDU response received during a secure session.

    To unprotect an APDU response, the SecureMessaging class performs the following actions:

    1. Verifies the RAPDU CC by computing the MAC of the concatenation of DO'87’ and DO'99’.
    2. Decrypts the data of DO'87’ with KSEnc.
    3. Builds the unprotected APDU response.

    Declaration

    Swift

    internal func unprotect(rapdu: APDUResponse) throws -> APDUResponse

    Parameters

    rapdu

    The APDU response to be unprotected.

    Return Value

    The unprotected APDU response.