pySim/card_key_provider.py

# coding=utf-8
"""Obtaining card parameters (mostly key data) from external source.

This module contains a base class and a concrete implementation of
obtaining card key material (or other card-individual parameters) from
an external data source.

This is used e.g. to keep PIN/PUK data in some file on disk, avoiding
the need of manually entering the related card-individual data on every
operation with pySim-shell.
"""

# (C) 2021 by Sysmocom s.f.m.c. GmbH
# All Rights Reserved
#
# Author: Philipp Maier
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

from typing import List, Dict, Optional

import abc
import csv

card_key_providers = []  # type: List['CardKeyProvider']


class CardKeyProvider(abc.ABC):
    """Base class, not containing any concrete implementation."""

    VALID_FIELD_NAMES = ['ICCID', 'ADM1',
                         'IMSI', 'PIN1', 'PIN2', 'PUK1', 'PUK2']

    # check input parameters, but do nothing concrete yet
    def _verify_get_data(self, fields: List[str] = [], key: str = 'ICCID', value: str = "") -> Dict[str, str]:
        """Verify multiple fields for identified card.

        Args:
                fields : list of valid field names such as 'ADM1', 'PIN1', ... which are to be obtained
                key : look-up key to identify card data, such as 'ICCID'
                value : value for look-up key to identify card data
        Returns:
                dictionary of {field, value} strings for each requested field from 'fields'
        """
        for f in fields:
            if (f not in self.VALID_FIELD_NAMES):
                raise ValueError("Requested field name '%s' is not a valid field name, valid field names are: %s" %
                                 (f, str(self.VALID_FIELD_NAMES)))

        if (key not in self.VALID_FIELD_NAMES):
            raise ValueError("Key field name '%s' is not a valid field name, valid field names are: %s" %
                             (key, str(self.VALID_FIELD_NAMES)))

        return {}

    def get_field(self, field: str, key: str = 'ICCID', value: str = "") -> Optional[str]:
        """get a single field from CSV file using a specified key/value pair"""
        fields = [field]
        result = self.get(fields, key, value)
        return result.get(field)

    @abc.abstractmethod
    def get(self, fields: List[str], key: str, value: str) -> Dict[str, str]:
        """Get multiple card-individual fields for identified card.

        Args:
                fields : list of valid field names such as 'ADM1', 'PIN1', ... which are to be obtained
                key : look-up key to identify card data, such as 'ICCID'
                value : value for look-up key to identify card data
        Returns:
                dictionary of {field, value} strings for each requested field from 'fields'
        """


class CardKeyProviderCsv(CardKeyProvider):
    """Card key provider implementation that allows to query against a specified CSV file"""
    csv_file = None
    filename = None

    def __init__(self, filename: str):
        """
        Args:
                filename : file name (path) of CSV file containing card-individual key/data
        """
        self.csv_file = open(filename, 'r')
        if not self.csv_file:
            raise RuntimeError("Could not open CSV file '%s'" % filename)
        self.filename = filename

    def get(self, fields: List[str], key: str, value: str) -> Dict[str, str]:
        super()._verify_get_data(fields, key, value)

        self.csv_file.seek(0)
        cr = csv.DictReader(self.csv_file)
        if not cr:
            raise RuntimeError(
                "Could not open DictReader for CSV-File '%s'" % self.filename)
        cr.fieldnames = [field.upper() for field in cr.fieldnames]

        rc = {}
        for row in cr:
            if row[key] == value:
                for f in fields:
                    if f in row:
                        rc.update({f: row[f]})
                    else:
                        raise RuntimeError("CSV-File '%s' lacks column '%s'" %
                                           (self.filename, f))
        return rc


def card_key_provider_register(provider: CardKeyProvider, provider_list=card_key_providers):
    """Register a new card key provider.

    Args:
            provider : the to-be-registered provider
            provider_list : override the list of providers from the global default
    """
    if not isinstance(provider, CardKeyProvider):
        raise ValueError("provider is not a card data provier")
    provider_list.append(provider)


def card_key_provider_get(fields, key: str, value: str, provider_list=card_key_providers) -> Dict[str, str]:
    """Query all registered card data providers for card-individual [key] data.

    Args:
            fields : list of valid field names such as 'ADM1', 'PIN1', ... which are to be obtained
            key : look-up key to identify card data, such as 'ICCID'
            value : value for look-up key to identify card data
            provider_list : override the list of providers from the global default
    Returns:
            dictionary of {field, value} strings for each requested field from 'fields'
    """
    for p in provider_list:
        if not isinstance(p, CardKeyProvider):
            raise ValueError(
                "provider list contains element which is not a card data provier")
        result = p.get(fields, key, value)
        if result:
            return result
    return {}


def card_key_provider_get_field(field: str, key: str, value: str, provider_list=card_key_providers) -> Optional[str]:
    """Query all registered card data providers for a single field.

    Args:
            field : name valid field such as 'ADM1', 'PIN1', ... which is to be obtained
            key : look-up key to identify card data, such as 'ICCID'
            value : value for look-up key to identify card data
            provider_list : override the list of providers from the global default
    Returns:
            dictionary of {field, value} strings for the requested field
    """
    for p in provider_list:
        if not isinstance(p, CardKeyProvider):
            raise ValueError(
                "provider list contains element which is not a card data provier")
        result = p.get_field(field, key, value)
        if result:
            return result
    return None