YateOTA – JSON API to encode UD(s)/APDU(s)

How to use JSON API to encode OTA User Data and Application Protocol Data Unit

This API is used to encode OTA messages called UDs.

These UDs can modify files on the SIM (RFM) or manage applets on the SIM (RAM).

Request: generate_uds

Generate and retrieve uds and apdus for updating RFM fields for multiple participants(SIMs).
This request has multiple formats in which it can be sent:
{
    "request": "generate_uds",
    "node": "ota",
    "params": {
        "type": "Type of command: RFM/RAM. Only RFM is currently supported. Required.",
        "tar_type": "Type of tar to use for generating UDs: sim/usim/isim. Required.",
        "participant": [
            {
                "kic": "Key Identifier for ciphering. Used for encryption. Size: 16/24 bytes. Format: hex",
                "kid": "Key Identifier for RC/CC/DS. Used to verify integrity data. Size: 16/24 bytes. Format: hex",
                "kik": "Key Identifier for protecting KIc and KID.",
                "ota_counter": "Counter used for replay detection and sequence integrity. Size: 5 bytes. Format: hex. Common: 0000000000.",
                "ota_profile": {
                    "cla": "Class Byte. The class byte shall be coded according to section 11.1.4.1 in GlobalPlatform Card Specification version 2.3. Size: 1 byte. Format: hex. Common: 80",
                    "spi": "Security Parameter Indicator. Specifies if algorithm is used, if PoR is ciphered etc. Size: 2 bytes. Format: hex. Common: 1621",
                    "kic": "Key and algorithm Identifier for ciphering. Algorithm type used for encryption. Size: 1 byte. Format: hex. Common: 15",
                    "kid": "Key and algorithm Identifier for RC/CC/DS. Algorithm type used to  compute RC/CC/DS field to verify integrity data. Size: 1 byte. Format: hex. Common: 15",
                    "tar_ram": "Toolkit Application Reference for RAM. Size: 3 byte. Format: hex. Common: 000000",
                    "tar_rfm_sim": "Toolkit Application Reference for RFM SIM. Size: 3 byte. Format: hex. Common: b00010",
                    "tar_rfm_usim": "Toolkit Application Reference for RFM USIM. Size: 3 byte. Format: hex. Common: b00001",
                    "tar_rfm_isim": "Toolkit Application Reference for RFM ISIM. Size: 3 byte. Format: hex. Common: b00020"
                }
            }
        ],
        "commands": [
            {
                "profile": "String. Optional. Name of the profile to use. If not set, default profile will be used",
                "app": "String. Required. RFM application to update: gsm/telecom/usim",
                "batch": [
                    {
                        "addr": "String or Array if case file in located in directory",
                        "values": "String or Object. If string, it contains the new value for the field. If object with \"old\" and \"new\" keys, then generated UDs will try to encode only the different between the two values."
                    }
                ]
            }
        ]
    }
}
{
    "request": "generate_uds",
    "node": "ota",
    "params": {
        "type": "Type of command: RFM/RAM. Only RFM is currently supported. Required.",
        "tar_type": "Type of tar to use for generating UDs: sim/usim/isim. Required.",
        "participant": [
            {
                "kic": "Key Identifier for ciphering. Used for encryption. Size: 16/24 bytes. Format: hex",
                "kid": "Key Identifier for RC/CC/DS. Used to verify integrity data. Size: 16/24 bytes. Format: hex",
                "kik": "Key Identifier for protecting KIc and KID.",
                "ota_counter": "Counter used for replay detection and sequence integrity. Size: 5 bytes. Format: hex. Common: 0000000000.",
                "ota_profile": {
                    "cla": "Class Byte. The class byte shall be coded according to section 11.1.4.1 in GlobalPlatform Card Specification version 2.3. Size: 1 byte. Format: hex. Common: 80",
                    "spi": "Security Parameter Indicator. Specifies if algorithm is used, if PoR is ciphered etc. Size: 2 bytes. Format: hex. Common: 1621",
                    "kic": "Key and algorithm Identifier for ciphering. Algorithm type used for encryption. Size: 1 byte. Format: hex. Common: 15",
                    "kid": "Key and algorithm Identifier for RC/CC/DS. Algorithm type used to  compute RC/CC/DS field to verify integrity data. Size: 1 byte. Format: hex. Common: 15",
                    "tar_ram": "Toolkit Application Reference for RAM. Size: 3 byte. Format: hex. Common: 000000",
                    "tar_rfm_sim": "Toolkit Application Reference for RFM SIM. Size: 3 byte. Format: hex. Common: b00010",
                    "tar_rfm_usim": "Toolkit Application Reference for RFM USIM. Size: 3 byte. Format: hex. Common: b00001",
                    "tar_rfm_isim": "Toolkit Application Reference for RFM ISIM. Size: 3 byte. Format: hex. Common: b00020"
                }
            }
        ],
        "apdus": "Array of already generated APDUs to use to generate UDs. This is required unless commands is present."
    }
}
Examples: generate_uds
Generate UD(s) and APDU(s) for every participant.
It updates the first 2 bytes of EF 6F05 with value 'AABB'.
{
    "request": "generate_uds",
    "node": "ota",
    "params": {
        "type": "RFM",
        "tar_type": "usim",
        "participant": [
            {
                "kic": "86ADE6DAF787FF199ACB51FFA118F765",
                "kid": "D6490DCB0EC849A66E43A455916D7DC0",
                "kik": "DEEACC5323A3FCE76EB3691F0676DFC0",
                "ota_counter": "000000005e",
                "ota_profile": {
                    "cla": "80",
                    "spi": "1621",
                    "kid": "15",
                    "kic": "15",
                    "tar_ram": "000000",
                    "tar_rfm_sim": "b00010",
                    "tar_rfm_usim": "b00001",
                    "tar_rfm_isim": "b00020"
                }
            }
        ],
        "commands": {
            "app": "gsm",
            "batch": [
                {
                    "addr": "6F05",
                    "values": "AABB"
                }
            ]
        }
    }
}
Generate UD(s) and APDU(s) for every participant.
It finds the differences between old value and new value and updates EF 4F20 in DF 5F3B under USIM.
{
    "request": "generate_uds",
    "node": "ota",
    "params": {
        "type": "RFM",
        "tar_type": "usim",
        "participant": [
            {
                "kic": "86ADE6DAF787FF199ACB51FFA118F765",
                "kid": "D6490DCB0EC849A66E43A455916D7DC0",
                "kik": "DEEACC5323A3FCE76EB3691F0676DFC0",
                "ota_counter": "000000005e",
                "ota_profile": {
                    "cla": "80",
                    "spi": "1621",
                    "kid": "15",
                    "kic": "15",
                    "tar_ram": "000000",
                    "tar_rfm_sim": "b00010",
                    "tar_rfm_usim": "b00001",
                    "tar_rfm_isim": "b00020"
                }
            }
        ],
        "commands": {
            "profile": "Elatec_new",
            "app": "usim",
            "batch": [
                {
                    "addr": [
                        "5F3B",
                        "4F20"
                    ],
                    "values": {
                        "old": "C6B5A841AC6DEC9500",
                        "new": "C6B5A841AC6DEE9500"
                    }
                }
            ]
        }
    }
}
Generate UD(s) and APDU(s) for every participant.
It updates 3 records in EF 6F42 under Telecom.
{
    "request": "generate_uds",
    "node": "ota",
    "params": {
        "type": "RFM",
        "tar_type": "sim",
        "participant": [
            {
                "kic": "86ADE6DAF787FF199ACB51FFA118F765",
                "kid": "D6490DCB0EC849A66E43A455916D7DC0",
                "kik": "DEEACC5323A3FCE76EB3691F0676DFC0",
                "ota_counter": "000000005e",
                "ota_profile": {
                    "cla": "80",
                    "spi": "1621",
                    "kid": "15",
                    "kic": "15",
                    "tar_ram": "000000",
                    "tar_rfm_sim": "b00010",
                    "tar_rfm_usim": "b00001",
                    "tar_rfm_isim": "b00020"
                }
            }
        ],
        "commands": {
            "app": "telecom",
            "batch": [
                {
                    "addr": "6F42",
                    "values": {
                        "1": "FFFFFFFFFFFFFFFFFFFFFFFFFDFFFFFFFFFFFFFFFFFFFFFFFF0591880200F3FFFFFFFFFFFFFFFFFF",
                        "2": "FFFFFFFFFFFFFFFFFFFFFFFFFDFFFFFFFFFFFFFFFFFFFFFFFF069169830840F4FFFFFFFFFFFFFFFF",
                        "3": "FFFFFFFFFFFFFFFFFFFFFFFFFDFFFFFFFFFFFFFFFFFFFFFFFF0591880200F3FFFFFFFFFFFFFFFFFF"
                    }
                }
            ]
        }
    }
}
Generate UD(s) for every participant by specifying APDUs.
{
    "request": "generate_uds",
    "node": "ota",
    "params": {
        "type": "RFM",
        "tar_type": "usim",
        "participant": [
            {
                "kic": "86ADE6DAF787FF199ACB51FFA118F765",
                "kid": "D6490DCB0EC849A66E43A455916D7DC0",
                "kik": "DEEACC5323A3FCE76EB3691F0676DFC0",
                "ota_counter": "000000005e",
                "ota_profile": {
                    "cla": "80",
                    "spi": "1621",
                    "kid": "15",
                    "kic": "15",
                    "tar_ram": "000000",
                    "tar_rfm_sim": "b00010",
                    "tar_rfm_usim": "b00001",
                    "tar_rfm_isim": "b00020"
                }
            }
        ],
        "apdus": [
            "00A40004026F42",
            "00DC0104260581880205F3FFFFFFFFFDFFFFFFFFFFFFFFFFFFFFFFFF0581880205F3FFFFFFFFFFFFFFFFFF",
            "00A40004026F46",
            "00D60000110054657374FFFFFFFFFFFFFFFFFFFFFFFF"
        ]
    }
}