Hoernchen has uploaded this change for review.
ota: indefinite length en/decoding support
Adds TS 102 226 tables 5.2a/5.10a indefinite length coding,
recommended by TS 102 226 5.2.1 for RAM/RFM over HTTPS.
Noteworthy notable things to note:
- encode_expanded_cmd()
indefinite version -> inner C-APDU TLVs are still definite
- decode_expanded_resp()s returned container does not care, but
Indef has no 'number of executed commands' TLV -> number_of_commands
is the R-APDU count.
Indef len is traversed using a small EOC helper because construct BER-TLV
only understands definite.
Tests are being fed with some known-good values from my sja5 sessions.
Change-Id: I4e023112e98729489ed443eec3ed5ab45c773b17
---
M pySim/ota.py
M tests/unittests/test_ota.py
2 files changed, 151 insertions(+), 14 deletions(-)
git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/46/43546/1
diff --git a/pySim/ota.py b/pySim/ota.py
index 30d9869..2083f46 100644
--- a/pySim/ota.py
+++ b/pySim/ota.py
@@ -67,6 +67,8 @@
# 5.2.1.4 Script Chaining TLV
# 5.2.2 Expanded Remote response structure (tables 5.10 .. 5.16)
#
+# definite length coding and indefinite length coding are supported.
+#
# BER-TLV tag values from ETSI TS 101 220 V19.0.0 tables 7.18, 7.19, 7.20
# C-APDU / R-APDU ETSI TS 102 223 Section 8.35 + 8.36
# inside these the CR flag of the tag is 0 (TS 101 220 tables 7.19/7.20),
@@ -112,14 +114,24 @@
def _encode(self, obj, context, path):
return h2b(obj['response_data']) + h2b(obj['status_word'])
-#### Command Scripting template TS 102 226 table 5.2, TS 101 220 tables 7.18/7.19
+#### Command Scripting template TS 102 226 tables 5.2 / 5.2a, TS 101 220 tables 7.18/7.19
+#
+# The two TS 101 220 table 7.18 length codings use different template tags:
+# - definite tag AA
+# - indefinite AE
+# In both codings the inner Command TLVs use definite length coding, only the
+# surrounding template differs.
# TS 102 223 8.35
ExpandedC_APDU = Struct('_tag'/Const(b'\x22'),
'c_apdu'/Prefixed(BerTlvLen, HexAdapter(GreedyBytes)))
+# shared by both length codings.
+ExpandedCmdItems = GreedyRange(ExpandedC_APDU)
+
+# Command Scripting template for only for definite length coding
ExpandedCmd = Struct('_tag'/Const(b'\xaa'),
- 'commands'/Prefixed(BerTlvLen, GreedyRange(ExpandedC_APDU)))
+ 'commands'/Prefixed(BerTlvLen, ExpandedCmdItems))
#### Response Scripting template TS 102 226 tables 5.10-5.16, TS 101 220 table 7.20
@@ -148,39 +160,87 @@
Enum(Int8ub, no_previous_script=1,
not_supported=2, unable_to_process=3)))
+# response TLVs shared by the def and indef Response Scripting templates
+ExpandedRespItems = GreedyRange(Select(ExpandedR_APDU,
+ ExpandedBadFormat,
+ ExpandedImmediateActionResp,
+ ExpandedScriptChainingResp))
+
# - starts with the "Number of executed command TLV objects" (table 5.10/5.13/5.15)
# - followed by a sequence of R-APDU TLVs
# - and/or one of the error # response TLVs
ExpandedRemoteResp = Struct('_tag'/Const(b'\xab'),
'body'/Prefixed(BerTlvLen, Struct(
'num_executed'/ExpandedNumExecuted,
- 'responses'/GreedyRange(Select(ExpandedR_APDU,
- ExpandedBadFormat,
- ExpandedImmediateActionResp,
- ExpandedScriptChainingResp)))))
+ 'responses'/ExpandedRespItems)))
-def encode_expanded_cmd(apdus: Union[bytes, List[bytes]]) -> bytes:
- """builds the Command Scripting template, TS 102 226 5.2.1, definite length coding
+#### Indefinite length coding (ISO/IEC 8825-1, TS 102 226 tables 5.2a/5.10a)
+#
+# construct BER-TLV support is definite len only, so the indef length
+# coding, a template like "<tag> 80 <definite-length inner TLVs> 00 00",
+# is handled here at the template level rather than inside BerTlvLength.
+
+def _read_ber_tlv_len(data: bytes, offset: int) -> Tuple[int, int]:
+ """Parse the definite BER-TLV len, return (length_value, number_of_length_octets) """
+ first = data[offset]
+ if first < 0x80:
+ return first, 1
+ num_octets = first & 0x7f
+ if num_octets == 0:
+ raise ValueError('nested indef length coding is not supported')
+ return int.from_bytes(data[offset+1:offset+1+num_octets], 'big'), 1 + num_octets
+
+def _indefinite_content(data: bytes, tag: int) -> bytes:
+ """Returns the content octets of an indef lengh template like
+ "<tag> 80 <content> 00 00" """
+ if len(data) < 4 or data[0] != tag:
+ raise ValueError('expected indefinite-length template tag 0x%02x' % tag)
+ if data[1] != 0x80:
+ raise ValueError('expected indefinite length indicator 0x80, got 0x%02x' % data[1])
+ off = 2
+ while off < len(data):
+ if data[off] == 0x00:
+ if data[off:off+2] != b'\x00\x00':
+ raise ValueError('malformed end-of-contents octets')
+ return data[2:off]
+ length, len_octets = _read_ber_tlv_len(data, off + 1)
+ off += 1 + len_octets + length
+ raise ValueError('indefinite-length template without end-of-contents (00 00)')
+
+
+def encode_expanded_cmd(apdus: Union[bytes, List[bytes]],
+ length_coding: str = 'definite') -> bytes:
+ """builds the Command Scripting template, TS 102 226 5.2.1
Args:
apdus: single C-APDU bytes or list of C-APDUs bytes. Each
C-APDU is wrapped into a C-APDU TLV- This function does not add
or modify Le.
+ length_coding: 'definite' (the default, tag 'AA', table 5.2) or
+ 'indefinite' (tag 'AE', table 5.2a: 'AE 80 <cmd TLVs> 00 00').
+ Inner C-APDU TLVs use definite length coding in both cases.
Returns:
- encoded Command Scripting template (AA...) as bytes
+ encoded Command Scripting template as bytes
"""
if isinstance(apdus, (bytes, bytearray)):
apdus = [apdus]
- return ExpandedCmd.build({'commands': [{'c_apdu': b2h(a)} for a in apdus]})
+ commands = [{'c_apdu': b2h(a)} for a in apdus]
+ if length_coding == 'definite':
+ return ExpandedCmd.build({'commands': commands})
+ if length_coding == 'indefinite':
+ return b'\xae\x80' + ExpandedCmdItems.build(commands) + b'\x00\x00'
+ raise ValueError("Invalid length_coding: %r" % length_coding)
def decode_expanded_resp(data: bytes) -> Container:
- """Decode a Response Scripting template, TS 102 226 5.2.2 definite length
+ """Decode a Response Scripting template, TS 102 226 5.2.2 def and indef length
coding
returned Container has:
number_of_commands -- "number of executed command TLV objects" table 5.11
+ for definite coding. indefinite coding does not have
+ this TLV, so report the number of returned R-APDUs instead.
commands -- list of Containers, one per R-APDU TLV, each
with 'response_data' and 'status_word' hexstr
last_response_data -- response_data of the last R-APDU or ''
@@ -198,12 +258,19 @@
CompactRemoteResp so existing callers keep working."""
if isinstance(data, str):
data = h2b(data)
- parsed = ExpandedRemoteResp.parse(data)
+ if data[:1] == b'\xaf':
+ responses = ExpandedRespItems.parse(_indefinite_content(data, 0xaf))
+ num_executed = None
+ else:
+ parsed = ExpandedRemoteResp.parse(data)
+ responses = parsed['body']['responses']
+ num_executed = parsed['body']['num_executed']['number_of_commands']
+
commands = []
bad_format = None
immediate_action_response = None
script_chaining_response = None
- for item in parsed['body']['responses']:
+ for item in responses:
if 'r_apdu' in item:
commands.append(Container(response_data=item['r_apdu']['response_data'],
status_word=item['r_apdu']['status_word']))
@@ -216,7 +283,7 @@
last = commands[-1] if commands else None
# TS 102 226 5.2.1.1: 62F1 means response of a C-APDU was truncated, processing terminated
truncated = any(c['status_word'].lower() == '62f1' for c in commands)
- return Container(number_of_commands=parsed['body']['num_executed']['number_of_commands'],
+ return Container(number_of_commands=num_executed if num_executed is not None else len(commands),
commands=commands,
last_response_data=last['response_data'] if last else '',
last_status_word=last['status_word'] if last else None,
diff --git a/tests/unittests/test_ota.py b/tests/unittests/test_ota.py
index e7c7230..d3fa5a2 100644
--- a/tests/unittests/test_ota.py
+++ b/tests/unittests/test_ota.py
@@ -451,6 +451,76 @@
self.assertFalse(decode_expanded_resp(data).truncated)
+class ExpandedIndefiniteTestCase(unittest.TestCase):
+ """Indef len coding of expanded format TS 102 226 tables
+ 5.2a/5.10a; cmd tag AE, resp tag AF.
+ Golden vectors captured from live eUICC over SCP81/HTTPS."""
+
+ def test_cmd_single_golden(self):
+ # RAM GET DATA 80CA00E000 -> AE 80 | 22 05 80ca00e000 | 00 00
+ out = encode_expanded_cmd(h2b('80ca00e000'), length_coding='indefinite')
+ self.assertEqual(b2h(out), 'ae80220580ca00e0000000')
+
+ def test_cmd_multi_golden(self):
+ # RFM: SELECT MF / SELECT EF.ICCID / READ BINARY, each in one C-APDU
+ # TLV, wrapped in indef Command Scripting template
+ out = encode_expanded_cmd([h2b('00a4000c023f00'), h2b('00a4000c022fe2'),
+ h2b('00b000000a')], length_coding='indefinite')
+ self.assertEqual(b2h(out),
+ 'ae80220700a4000c023f00220700a4000c022fe2220500b000000a0000')
+
+ def test_cmd_definite_is_default(self):
+ # The default/explicit definite keeps the tag AA
+ self.assertEqual(encode_expanded_cmd(h2b('80ca00e000')),
+ encode_expanded_cmd(h2b('80ca00e000'), length_coding='definite'))
+ self.assertEqual(b2h(encode_expanded_cmd(h2b('80ca00e000'))), 'aa07220580ca00e000')
+
+ def test_cmd_invalid_length_coding(self):
+ with self.assertRaises(ValueError):
+ encode_expanded_cmd(h2b('80ca00e000'), length_coding='bogus')
+
+ def test_resp_rfm_golden(self):
+ # AF 80 | 23 02 9000 | 23 02 9000 | 23 0c <ICCID> 9000 | 00 00
+ # indef res has no "number of executed" TLV.
+ dec = decode_expanded_resp(h2b(
+ 'af8023029000230290002' '30c988812010000408608149000' '0000'))
+ self.assertEqual(len(dec.commands), 3)
+ self.assertEqual([(c.status_word, c.response_data) for c in dec.commands],
+ [('9000', ''), ('9000', ''), ('9000', '98881201000040860814')])
+ self.assertEqual(dec.last_status_word, '9000')
+ self.assertEqual(dec.last_response_data, '98881201000040860814')
+ # report the R-APDU count instead
+ self.assertEqual(dec.number_of_commands, 3)
+
+ def test_resp_ram_golden(self):
+ # RAM GET DATA: R-APDU carrying the SD key info TLV + SW.
+ resp = ('af802334e030c00403308810c00402308810c00401308810c00402408810'
+ 'c00401408510c00403018810c00402018810c004010188109000' '0000')
+ dec = decode_expanded_resp(h2b(resp))
+ self.assertEqual(len(dec.commands), 1)
+ self.assertEqual(dec.last_status_word, '9000')
+ self.assertEqual(dec.last_response_data,
+ 'e030c00403308810c00402308810c00401308810c00402408810'
+ 'c00401408510c00403018810c00402018810c00401018810')
+
+ def test_resp_definite_still_parses(self):
+ # same decoder still handles the definite AB template.
+ dec = decode_expanded_resp(h2b('ab0780010123029000'))
+ self.assertEqual(dec.number_of_commands, 1)
+ self.assertEqual(dec.last_status_word, '9000')
+
+ def test_resp_indefinite_bad_format(self):
+ # AF 80 | 90 01 01 | 00 00 unknown_tag no R-APDU
+ dec = decode_expanded_resp(h2b('af8090010100 00'.replace(' ', '')))
+ self.assertEqual(str(dec.bad_format), 'unknown_tag')
+ self.assertIsNone(dec.last_status_word)
+
+ def test_resp_missing_eoc_raises(self):
+ # AF 80 | 23 02 9000 without end-of-contents.
+ with self.assertRaises(ValueError):
+ decode_expanded_resp(h2b('af8023029000'))
+
+
class ExpandedSmsPipelineTestCase(unittest.TestCase):
"""expanded format + TS 102 225 SMS security witj 3DES keyset,
to ensure remote_format does not affect the compact path"""
To view, visit change 43546. To unsubscribe, or for help writing mail filters, visit settings.