Arthur de Jong

Open Source / Free Software developer

summaryrefslogtreecommitdiffstats
path: root/stdnum/meid.py
blob: 9f25379093a98c4c4dd7efe32cd7e48c29c733d3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
# meid.py - functions for handling Mobile Equipment Identifiers (MEIDs)
#
# Copyright (C) 2010-2017 Arthur de Jong
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library 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
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
# 02110-1301 USA

"""MEID (Mobile Equipment Identifier).

The Mobile Equipment Identifier is used to identify a physical piece of
CDMA mobile station equipment.

>>> validate('AF 01 23 45 0A BC DE C')
'AF0123450ABCDE'
>>> validate('29360 87365 0070 3710 0')
'AF0123450ABCDE'
>>> validate('29360 87365 0070 3710 0', strip_check_digit=False)
'AF0123450ABCDEC'
>>> validate('29360 87365 0070 3710 1')
Traceback (most recent call last):
    ...
InvalidChecksum: ...
>>> format('af0123450abcDEC', add_check_digit=True)
'AF 01 23 45 0A BC DE C'
>>> format('af0123450abcDEC', format='dec', add_check_digit=True)
'29360 87365 0070 3710 0'
"""

from stdnum.exceptions import *
from stdnum.util import clean, isdigits


_hex_alphabet = '0123456789ABCDEF'


def _cleanup(number):
    """Remove any grouping information from the number and removes surrounding
    whitespace."""
    return clean(number, ' -').strip().upper()


def _ishex(number):
    for x in number:
        if x not in _hex_alphabet:
            return False
    return True


def _parse(number):
    number = _cleanup(number)
    if len(number) in (14, 15):
        # 14 or 15 digit hex representation
        if not _ishex(number):
            raise InvalidFormat()
        return number[0:14], number[14:]
    elif len(number) in (18, 19):
        # 18-digit decimal representation
        if not isdigits(number):
            raise InvalidFormat()
        return number[0:18], number[18:]
    else:
        raise InvalidLength()


def calc_check_digit(number):
    """Calculate the check digit for the number. The number should not
    already have a check digit."""
    # both the 18-digit decimal format and the 14-digit hex format
    # containing only decimal digits should use the decimal Luhn check
    from stdnum import luhn
    if isdigits(number):
        return luhn.calc_check_digit(number)
    else:
        return luhn.calc_check_digit(number, alphabet=_hex_alphabet)


def compact(number, strip_check_digit=True):
    """Convert the MEID number to the minimal (hexadecimal) representation.
    This strips grouping information, removes surrounding whitespace and
    converts to hexadecimal if needed. If the check digit is to be preserved
    and conversion is done a new check digit is recalculated."""
    # first parse the number
    number, cd = _parse(number)
    # strip check digit if needed
    if strip_check_digit:
        cd = ''
    # convert to hex if needed
    if len(number) == 18:
        number = '%08X%06X' % (int(number[0:10]), int(number[10:18]))
        if cd:
            cd = calc_check_digit(number)
    # put parts back together again
    return number + cd


def _bit_length(n):
    """Return the number of bits necessary to store the number in binary."""
    try:
        return n.bit_length()
    except AttributeError:  # pragma: no cover (Python 2.6 only)
        import math
        return int(math.log(n, 2)) + 1


def validate(number, strip_check_digit=True):
    """Check if the number is a valid MEID number. This converts the
    representation format of the number (if it is decimal it is not converted
    to hexadecimal)."""
    # first parse the number
    number, cd = _parse(number)
    from stdnum import luhn
    if len(number) == 18:
        # decimal format can be easily determined
        if cd:
            luhn.validate(number + cd)
        # convert to hex
        manufacturer_code = int(number[0:10])
        serial_num = int(number[10:18])
        if _bit_length(manufacturer_code) > 32 or _bit_length(serial_num) > 24:
            raise InvalidComponent()
        number = '%08X%06X' % (manufacturer_code, serial_num)
        cd = calc_check_digit(number)
    elif isdigits(number):
        # if the remaining hex format is fully decimal it is an IMEI number
        from stdnum import imei
        imei.validate(number + cd)
    else:
        # normal hex Luhn validation
        if cd:
            luhn.validate(number + cd, alphabet=_hex_alphabet)
    if strip_check_digit:
        cd = ''
    return number + cd


def is_valid(number):
    """Check if the number is a valid MEID number."""
    try:
        return bool(validate(number))
    except ValidationError:
        return False


def format(number, separator=' ', format=None, add_check_digit=False):
    """Reformat the number to the standard presentation format. The separator
    used can be provided. If the format is specified (either 'hex' or 'dec')
    the number is reformatted in that format, otherwise the current
    representation is kept. If add_check_digit is True a check digit will be
    added if it is not present yet."""
    # first parse the number
    number, cd = _parse(number)
    # format conversions if needed
    if format == 'dec' and len(number) == 14:
        # convert to decimal
        number = '%010d%08d' % (int(number[0:8], 16), int(number[8:14], 16))
        if cd:
            cd = calc_check_digit(number)
    elif format == 'hex' and len(number) == 18:
        # convert to hex
        number = '%08X%06X' % (int(number[0:10]), int(number[10:18]))
        if cd:
            cd = calc_check_digit(number)
    # see if we need to add a check digit
    if add_check_digit and not cd:
        cd = calc_check_digit(number)
    # split number according to format
    if len(number) == 14:
        number = [number[i * 2:i * 2 + 2]
                  for i in range(7)] + [cd]
    else:
        number = (number[:5], number[5:10], number[10:14], number[14:], cd)
    return separator.join(x for x in number if x)


def to_binary(number):
    """Convert the number to its binary representation (without the check
    digit)."""
    from binascii import a2b_hex
    return a2b_hex(compact(number, strip_check_digit=True))


def to_pseudo_esn(number):
    """Convert the provided MEID to a pseudo ESN (pESN). The ESN is returned
    in compact hexadecimal representation."""
    # return the last 6 digits of the SHA1  hash prefixed with the reserved
    # manufacturer code
    import hashlib
    return '80' + hashlib.sha1(to_binary(number)).hexdigest()[-6:].upper()