Two documentation-only patches expanding the Doxygen \defgroup block in the public A5 header. No algorithmic or behavioral change.
Patch 1/2 describes the A5/x variant family used by GMR-1 (A5/0, A5/1, n=2..7 reserved), cites the Driessen et al. IEEE S&P 2012 paper as the public algorithm reference, and adds a HYPOTHESIS paragraph noting a conjectured equivalence between gmr1_a5_1() and ETSI TETRA's TEA1 cipher (EN 300 392-7). Motivation: if the equivalence holds, TEA1 reference implementations become an independent cross-validation source for gmr1_a5_1() output on matching (key, fn) inputs. The conjecture is explicitly labelled.
Patch 2/2 records the register layout typically observed in deployed GMR-1 hardware cipher peripherals (16-bit MMIO window, four parameter words, selector, auxiliary word, and mode / control word with start / direction / algorithm-family-selector bit fields), plus the observation that the peripheral is usually a multi-cipher accelerator with additional algorithm-family slots beyond A5-GMR-1. The intent is to give capture-side analysis tool builders a concrete interface reference.
Independent of the earlier "l1/a5: harden dispatcher default and expand docs" series on the list; both apply on top of master in either order.
Dominik Bay (2): l1/a5: document A5/x variants and note TEA1 equivalence hypothesis l1/a5: document hardware cipher-block register layout and mode enum
include/osmocom/gmr1/l1/a5.h | 44 ++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+)
Expand the \defgroup a5 block in the public header to explicitly describe the A5/x variant family used by GMR-1:
* A5/0: no ciphering (keystream = zero), useful for test and for indicating no-cipher mode * A5/1: GMR-1 keystream generator, implemented by gmr1_a5_1(), algorithm as described in B. Driessen, R. Hund, C. Willems, C. Paar, T. Holz, 'Don't Trust Satellite Phones', IEEE S&P 2012 * n=2..7: reserved by the dispatcher, not defined in GMR-1
Add a HYPOTHESIS paragraph noting that gmr1_a5_1() is conjectured to be structurally equivalent to ETSI TETRA's TEA1 (EN 300 392-7), so that TEA1 reference implementations can be used as a cross-validation source for gmr1_a5_1() output on matching (key, fn) inputs. If confirmed, this is a practical interop lever for builders working across GMR-1 and TETRA.
The hypothesis is noted with explicit uncertainty. No algorithmic change.
Signed-off-by: Dominik Bay eimann@etherkiller.de --- include/osmocom/gmr1/l1/a5.h | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)
diff --git a/include/osmocom/gmr1/l1/a5.h b/include/osmocom/gmr1/l1/a5.h index f0ea06b..d15efd5 100644 --- a/include/osmocom/gmr1/l1/a5.h +++ b/include/osmocom/gmr1/l1/a5.h @@ -22,6 +22,29 @@
/*! \defgroup a5 A5 ciphering algorithm * \ingroup l1 + * + * The GMR-1 standard uses an A5/x-family stream cipher analogous to + * GSM A5. Variants defined for GMR-1 are: + * + * - A5/0: no ciphering; keystream is all zeros. Used for test and + * for indicating no-cipher mode. + * - A5/1: stream cipher implemented by gmr1_a5_1(). The algorithm + * is described by B. Driessen, R. Hund, C. Willems, C. Paar, + * T. Holz, "Don't Trust Satellite Phones: A Security Analysis of + * Two Satphone Standards", IEEE Symposium on Security and + * Privacy, 2012. + * + * Variants n=2..7 are reserved by the dispatcher and are not + * defined by the GMR-1 standard. + * + * \par Cross-standard equivalence (HYPOTHESIS) + * gmr1_a5_1() is conjectured to be structurally equivalent to ETSI + * TETRA's TEA1 cipher (ETSI EN 300 392-7), in the sense that a TEA1 + * reference implementation should produce matching keystream output + * for identical (key, frame-number) inputs. If confirmed, this + * enables cross-validation of gmr1_a5_1() against an + * independently-sourced TEA1 implementation. + * * @{ */
Deployed GMR-1 devices typically run the A5 algorithm family in a dedicated cipher peripheral rather than in software. Record the observed register layout in the public Doxygen block so users reading captures or building capture-side analysis tools have a reference.
Register layout (16-bit words at fixed offsets from a per-device base address):
+0x00 .. +0x06 : four 16-bit parameter words (key / IV material) +0x08 : 16-bit selector / frame word +0x0a : 16-bit auxiliary parameter +0x0c : 16-bit mode / control word with bit fields: 0x0001 : start 0x0002 : direction (1 = decipher, 0 = encipher) 0x0004 / 0x0008 : algorithm-family selector (mutually exclusive bases)
The peripheral typically exposes at least one additional algorithm-family slot beyond A5-GMR-1, consistent with a shared multi-cipher accelerator. The software reimplementation in this module is the reference for off-line SDR / capture analysis; it is unrelated to any specific hardware implementation.
Purely cosmetic, no behavioral change.
Signed-off-by: Dominik Bay eimann@etherkiller.de --- include/osmocom/gmr1/l1/a5.h | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)
diff --git a/include/osmocom/gmr1/l1/a5.h b/include/osmocom/gmr1/l1/a5.h index d15efd5..d3fe3a7 100644 --- a/include/osmocom/gmr1/l1/a5.h +++ b/include/osmocom/gmr1/l1/a5.h @@ -45,6 +45,27 @@ * enables cross-validation of gmr1_a5_1() against an * independently-sourced TEA1 implementation. * + * \par Typical hardware implementations + * Deployed GMR-1 devices typically run the A5 algorithm family in a + * dedicated cipher peripheral rather than in software. The observed + * register layout is a 16-bit window at a per-device base address: + * \verbatim + * +0x00 .. +0x06 : four 16-bit parameter words (key / IV material) + * +0x08 : 16-bit selector / frame word + * +0x0a : 16-bit auxiliary parameter + * +0x0c : 16-bit mode / control word, bit fields: + * 0x0001 : start + * 0x0002 : direction (1 = decipher, 0 = encipher) + * 0x0004 / 0x0008 : algorithm-family selector + * (mutually exclusive bases) + * \endverbatim + * The peripheral typically exposes at least one additional + * algorithm-family slot beyond A5-GMR-1, consistent with a shared + * multi-cipher accelerator. The software reimplementation in this + * module is the reference for off-line SDR / capture analysis and + * for generating test vectors; it is unrelated to any specific + * hardware implementation. + * * @{ */
-
Dominik Bay