Added codec: modhex

Author: dhondta

README.md

@@ -277,6 +277,7 @@ CACTCGGTCGGCCATATGTTCGGCCATATGTTCGTCTGTTCACTCGCCCATACACT
 - [X] `base10`: simple conversion to decimal
 - [X] `base11`: conversion to digits with a "*a*"
 - [X] `base16`: simple conversion to hexadecimal (with a variant holding an alphabet with digits and letters inverted)
+- [X] `modhex`: [ModHex](https://developers.yubico.com/yubico-c/Manuals/modhex.1.html), the hexadecimal of YubiKeys (digits as `cbdefghijklnrtuv`)
 - [X] `base26`: conversion to alphabet letters
 - [X] `base32`: classical conversion according to the RFC4648 with all its variants ([zbase32](https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt), extended hexadecimal, [geohash](https://en.wikipedia.org/wiki/Geohash), [Crockford](https://www.crockford.com/base32))
 - [X] `base36`: [Base36](https://en.wikipedia.org/wiki/Base36) conversion to letters and digits (with a variant inverting both groups)

docs/pages/enc/base.md

@@ -183,6 +183,7 @@ This encoding implements various different versions of Base85.
 
 **Codec** | **Conversions** | **Aliases** | **Comment**
 :---: | :---: | --- | ---
+`modhex` | data <-> ModHex encoded text | `mod-hex`, `base16-modhex`, `yubikey-modhex` | [ModHex](https://developers.yubico.com/yubico-c/Manuals/modhex.1.html), the hexadecimal of YubiKeys with the digits `cbdefghijklnrtuv` ; decoding ignores the case, whitespaces and the delimiters `%`, `,`, `;` and `:`
 `base100` | text <-> Base100 encoded text | `base[-_]?100|emoji` | Python 3 only
 `base122` | text <-> Base122 encoded text | `base[-_]?122` | Python 3 only
 `base128` | text <-> Base128 encoded text | `base[-_]?128` | Relies on the ASCII charset
@@ -198,6 +199,13 @@ This encoding implements various different versions of Base85.
 `base65536` | data <-> Base65536 encoded text | `base[-_]?65536` | 16 bits per character, optimised for UTF-32
 `base131072` | data <-> Base131072 encoded text | `base[-_]?131072` | 17 bits per character, variant of the [base131072](https://docs.rs/base131072) Rust crate
 
+```python
+>>> codecs.encode("this is a test", "modhex")
+'ifhjhkiedchkiedchbdcifhgieif'
+>>> codecs.decode("IF:HJ:HK:IE", "modhex")
+'this'
+```
+
 ```python
 >>> codecs.encode("this is a test", "base100")
 '👫👟👠👪🐗👠👪🐗👘🐗👫👜👪👫'

src/codext/base/__init__.py

@@ -19,6 +19,7 @@
 from .base131072 import *
 from .baseN import *
 from .leb128 import *
+from .modhex import *
 from ..__common__ import *
 from ..__info__ import __version__
 

src/codext/base/modhex.py

@@ -0,0 +1,55 @@
+# -*- coding: UTF-8 -*-
+"""ModHex Codec - modified hexadecimal content encoding.
+
+ModHex (modified hexadecimal) is the hexadecimal encoding used by YubiKeys for their one-time passwords: the digits 0 to
+ f are replaced by the letters "cbdefghijklnrtuv", which are at the same positions on most keyboard layouts, as a
+ YubiKey types its output as a USB keyboard. Encoding gives the digits without delimiter (as typed by a YubiKey), while
+ decoding ignores the case, whitespaces and the delimiters "%", ",", ";" and ":" (as output by CyberChef).
+
+This codec:
+- en/decodes strings from str to str
+- en/decodes strings from bytes to bytes
+- decodes file content to str (read)
+- encodes file content from str to bytes (write)
+
+Reference: https://developers.yubico.com/yubico-c/Manuals/modhex.1.html
+"""
+from ..__common__ import *
+
+
+__examples__ = {
+    'enc(modhex|mod-hex|mod_hex|base16-modhex|yubikey-modhex)': {'\n\x14\x1e': "clbfbu", 'test': "ifhgieif", '': ""},
+    'dec(modhex)': {'clbfbu': "\n\x14\x1e", 'cl bf bu': "\n\x14\x1e", 'CL:BF:BU': "\n\x14\x1e", 'cl\r\nbf': "\n\x14",
+                    'cla': None, 'clb': None, 'clxx': None},
+    'enc-dec(modhex)': ["test", "This is a test", "@random{512,1024,2048}"],
+}
+__guess__ = ["modhex"]
+
+
+MODHEX, HEX = "cbdefghijklnrtuv", "0123456789abcdef"
+_ENC, _DEC = str.maketrans(HEX, MODHEX), {c: h for c, h in zip(MODHEX, HEX)}
+DELIMITERS = " \t\r\n%,;:"
+
+
+def modhex_encode(text, errors="strict"):
+    t = b(text)
+    return t.hex().translate(_ENC), len(t)
+
+
+def modhex_decode(text, errors="strict"):
+    _h, digits = handle_error("modhex", errors, decode=True), []
+    for i, c in enumerate(ensure_str(text).lower()):
+        if c in _DEC:
+            digits.append(_DEC[c])
+        elif c not in DELIMITERS:
+            _h(c, i)
+    # an odd number of digits leaves an incomplete byte, which is an error (or dropped if errors are not handled
+    #  strictly)
+    if len(digits) % 2:
+        _h(text[-1:], len(text) - 1)
+        digits = digits[:-1]
+    return bytes.fromhex("".join(digits)), len(text)
+
+
+add("modhex", modhex_encode, modhex_decode, r"^(?:mod[-_]?hex|base[-_]?16[-_]modhex|yubikey[-_]modhex)$",
+    entropy=4., expansion_factor=2., len_charset=16, printables_rate=1.)

tests/test_base.py

@@ -240,6 +240,14 @@ def test_codec_base64(self):
             self.assertEqual(codecs.decode(b64, enc), STR)
             self.assertEqual(codecs.decode(b(b64), enc), b(STR))
 
+    def test_codec_modhex(self):
+        # YubiKey's alphabet for the hexadecimal digits, the case and delimiters being ignored when decoding
+        self.assertEqual(codecs.encode(STR, "modhex"), codecs.encode(STR, "base16").lower().translate(
+                         str.maketrans("0123456789abcdef", "cbdefghijklnrtuv")))
+        self.assertEqual(codecs.decode(codecs.encode(STR, "modhex").upper(), "modhex"), STR)
+        # invalid characters and an incomplete byte are dropped when errors are not handled strictly
+        self.assertEqual(codecs.decode("cl?bfb", "modhex", "ignore"), "\n\x14")
+    
     def test_codec_base91(self):
         for b91, enc in zip([",X,<:WRT%yxth90oZB", ",N,<:MHJ%onjXzqeP1", "Jx&[jv4S3Wg>,71@Jk", "yJy^\\IDFsdc?Tof:L#"],
                             ["base91", "base91-inv", "base91-alt", "base91-alt-inv"]):