Clarify the Doxygen block on gmr1_a5(): - Document the accepted range of n as the GMR-1 A5/x selector, with only n=0 (no ciphering) and n=1 (A5-GMR-1) defined by the standard. - Spell out the behavior for each case, including the defensive zeroing now done for reserved values.
Add a \see reference on gmr1_a5_1() to the public algorithm description (Driessen, Hund, Willems, Paar, Holz, IEEE S&P 2012).
Purely cosmetic, no behavioral change.
Signed-off-by: Dominik Bay eimann@etherkiller.de --- src/l1/a5.c | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-)
diff --git a/src/l1/a5.c b/src/l1/a5.c index 105dcb2..24a4299 100644 --- a/src/l1/a5.c +++ b/src/l1/a5.c @@ -43,14 +43,17 @@
/*! \brief Main method to generate a A5/x cipher stream - * \param[in] n Which A5/x method to use + * \param[in] n Selects the A5/x variant (GMR-1 only defines n=0 and n=1) * \param[in] key 8 byte array for the key (as received from the SIM) * \param[in] fn Frame number * \param[in] nbits How many bits to generate * \param[out] dl Pointer to array of ubits to return Downlink cipher stream * \param[out] ul Pointer to array of ubits to return Uplink cipher stream * - * Currently only A5/0 and A5/1. + * For n=0 no ciphering is applied and the output buffers are zeroed. + * For n=1 the GMR-1 A5/1 keystream is generated by gmr1_a5_1(). + * Other values of n are reserved and also result in zeroed output buffers. + * * Either (or both) of dl/ul can be NULL if not needed. */ void @@ -226,6 +229,10 @@ _a5_1_output(uint32_t *r) * \param[out] ul Pointer to array of ubits to return Uplink cipher stream * * Either (or both) of dl/ul can be NULL if not needed. + * + * \see 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. */ void gmr1_a5_1(uint8_t *key, uint32_t fn, int nbits, ubit_t *dl, ubit_t *ul)