dexter has uploaded this change for review. ( https://gerrit.osmocom.org/c/pysim/+/41450?usp=email )
Change subject: card_key_provider: separate column decryption ......................................................................
card_key_provider: separate column decryption
The concrete class CardKeyProviderCsv supports the decryption of encrypted CSV columns (fields). However, this kind of mechanmism may also be useful in with other data formats we may implement in the future, so let' slplit the encryption part into a seperate class from which we may inherit.
Related: SYS#7725 Change-Id: I180457d4938f526d227c81020e4e03c6b3a57dab --- M pySim/card_key_provider.py 1 file changed, 46 insertions(+), 20 deletions(-)
git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/50/41450/1
diff --git a/pySim/card_key_provider.py b/pySim/card_key_provider.py index d5541b0..e1fa49e 100644 --- a/pySim/card_key_provider.py +++ b/pySim/card_key_provider.py @@ -10,7 +10,7 @@ operation with pySim-shell. """
-# (C) 2021-2024 by Sysmocom s.f.m.c. GmbH +# (C) 2021-2025 by Sysmocom s.f.m.c. GmbH # All Rights Reserved # # Author: Philipp Maier, Harald Welte @@ -89,33 +89,30 @@ dictionary of {field, value} strings for each requested field from 'fields' """
+class CardKeyFieldDecrypter(abc.ABC): + """ + A Card key field decryptor class that may be used by Card key provider implementations to add support for + a column-based encryption to protect sensitive material (cryptographic key material, ADM keys, etc.). + The sensitive material is encrypted using a "key-encryption key", occasionally also known as "transport key" + before it is stored into a file or database (see also GSMA FS.28). The "transport key" is then used to decrypt + the key material on demand using this class. + """
-class CardKeyProviderCsv(CardKeyProvider): - """Card key provider implementation that allows to query against a specified CSV file. - Supports column-based encryption as it is generally a bad idea to store cryptographic key material in - plaintext. Instead, the key material should be encrypted by a "key-encryption key", occasionally also - known as "transport key" (see GSMA FS.28).""" - IV = b'\x23' * 16 - csv_file = None - filename = None - - def __init__(self, filename: str, transport_keys: dict): + def _set_transport_keys(self, transport_keys: dict): """ + Set transport keys, usually one for each column. In some cases it is also possible to use a single key for multiple + columns (see also CRYPT_GROUPS) + Args: - filename : file name (path) of CSV file containing card-individual key/data transport_keys : a dict indexed by field name, whose values are hex-encoded AES keys for the - respective field (column) of the CSV. This is done so that different fields + respective field (column) of the CSV. This is done so that different fields (columns) can use different transport keys, which is strongly recommended by GSMA FS.28 """ - self.csv_file = open(filename, 'r') - if not self.csv_file: - raise RuntimeError("Could not open CSV file '%s'" % filename) - self.filename = filename - self.transport_keys = self.process_transport_keys(transport_keys) + self.transport_keys = self.__process_transport_keys(transport_keys)
@staticmethod - def process_transport_keys(transport_keys: dict): + def __process_transport_keys(transport_keys: dict): """Apply a single transport key to multiple fields/columns, if the name is a group.""" new_dict = {} for name, key in transport_keys.items(): @@ -127,12 +124,41 @@ return new_dict
def _decrypt_field(self, field_name: str, encrypted_val: str) -> str: - """decrypt a single field, if we have a transport key for the field of that name.""" + """ + Decrypt a single field. The decryption is only applied if we have a transport key is known under the provided + field name, otherwise the field is treated as plaintext and passed through as it is. + + Args: + field_name : name of the field to decrypt (used to identify which key to use) + encrypted_val : encrypted field value + + Returns: + plaintext field value + """ if not field_name in self.transport_keys: return encrypted_val cipher = AES.new(h2b(self.transport_keys[field_name]), AES.MODE_CBC, self.IV) return b2h(cipher.decrypt(h2b(encrypted_val)))
+class CardKeyProviderCsv(CardKeyFieldDecrypter, CardKeyProvider): + """Card key provider implementation that allows to query against a specified CSV file.""" + + IV = b'\x23' * 16 + csv_file = None + filename = None + + def __init__(self, filename: str, transport_keys: dict): + """ + Args: + filename : file name (path) of CSV file containing card-individual key/data + transport_keys : (see class CardKeyFieldDecrypter) + """ + self.csv_file = open(filename, 'r') + if not self.csv_file: + raise RuntimeError("Could not open CSV file '%s'" % filename) + self.filename = filename + self._set_transport_keys(transport_keys) + def get(self, fields: List[str], key: str, value: str) -> Dict[str, str]: super()._verify_get_data(fields, key, value)