libosmogsm  0.9.6.269-c2af
Osmocom GSM library
 All Data Structures Files Functions Variables Enumerations Enumerator Modules Pages
Crypto

Osmocom GSM/GPRS ciphering algorithm implementation. More...

Files

file  a5.c
 
file  gea.c
 

Macros

#define ENOTSUP   EINVAL
 
#define A5_R1_LEN   19
 
#define A5_R2_LEN   22
 
#define A5_R3_LEN   23
 
#define A5_R4_LEN   17 /* A5/2 only */
 
#define A5_R1_MASK   ((1<<A5_R1_LEN)-1)
 
#define A5_R2_MASK   ((1<<A5_R2_LEN)-1)
 
#define A5_R3_MASK   ((1<<A5_R3_LEN)-1)
 
#define A5_R4_MASK   ((1<<A5_R4_LEN)-1)
 
#define A5_R1_TAPS   0x072000 /* x^19 + x^18 + x^17 + x^14 + 1 */
 
#define A5_R2_TAPS   0x300000 /* x^22 + x^21 + 1 */
 
#define A5_R3_TAPS   0x700080 /* x^23 + x^22 + x^21 + x^8 + 1 */
 
#define A5_R4_TAPS   0x010800 /* x^17 + x^12 + 1 */
 
#define A51_R1_CLKBIT   0x000100
 
#define A51_R2_CLKBIT   0x000400
 
#define A51_R3_CLKBIT   0x000400
 
#define A52_R4_CLKBIT0   0x000400
 
#define A52_R4_CLKBIT1   0x000008
 
#define A52_R4_CLKBIT2   0x000080
 

Functions

void _a5_4 (const uint8_t *ck, uint32_t fn, ubit_t *dl, ubit_t *ul, bool fn_correct)
 Generate a GSM A5/4 cipher stream. More...
 
void _a5_3 (const uint8_t *key, uint32_t fn, ubit_t *dl, ubit_t *ul, bool fn_correct)
 Generate a GSM A5/3 cipher stream. More...
 
static uint32_t _a5_12_parity (uint32_t x)
 Computes parity of a 32-bit word. More...
 
static uint32_t _a5_12_majority (uint32_t v1, uint32_t v2, uint32_t v3)
 Compute majority bit from 3 taps. More...
 
static uint32_t _a5_12_clock (uint32_t r, uint32_t mask, uint32_t taps)
 Compute the next LFSR state. More...
 
static void _a5_1_clock (uint32_t r[], int force)
 GSM A5/1 Clocking function. More...
 
static uint8_t _a5_1_get_output (uint32_t r[])
 GSM A5/1 Output function. More...
 
void _a5_1 (const uint8_t *key, uint32_t fn, ubit_t *dl, ubit_t *ul)
 Generate a GSM A5/1 cipher stream. More...
 
void osmo_a5_1 (const uint8_t *key, uint32_t fn, ubit_t *dl, ubit_t *ul)
 
static void _a5_2_clock (uint32_t r[], int force)
 GSM A5/2 Clocking function. More...
 
static uint8_t _a5_2_get_output (uint32_t r[])
 GSM A5/2 Output function. More...
 
void _a5_2 (const uint8_t *key, uint32_t fn, ubit_t *dl, ubit_t *ul)
 Generate a GSM A5/1 cipher stream. More...
 
void osmo_a5_2 (const uint8_t *key, uint32_t fn, ubit_t *dl, ubit_t *ul)
 
int osmo_a5 (int n, const uint8_t *key, uint32_t fn, ubit_t *dl, ubit_t *ul)
 Main method to generate a A5/x cipher stream. More...
 
int gea4 (uint8_t *out, uint16_t len, uint8_t *kc, uint32_t iv, enum gprs_cipher_direction direction)
 Performs the GEA4 algorithm as in 3GPP TS 55.226 V9.0.0. More...
 
int gea3 (uint8_t *out, uint16_t len, uint8_t *kc, uint32_t iv, enum gprs_cipher_direction direction)
 Performs the GEA3 algorithm as in 3GPP TS 55.216 V6.2.0. More...
 
static LLIST_HEAD (gprs_ciphers)
 
int gprs_cipher_register (struct gprs_cipher_impl *ciph)
 
int gprs_cipher_load (const char *path)
 
int gprs_cipher_run (uint8_t *out, uint16_t len, enum gprs_ciph_algo algo, uint8_t *kc, uint32_t iv, enum gprs_cipher_direction dir)
 
unsigned gprs_cipher_key_length (enum gprs_ciph_algo algo)
 Obtain key lenght for given GPRS cipher. More...
 
int gprs_cipher_supported (enum gprs_ciph_algo algo)
 
uint32_t gprs_cipher_gen_input_ui (uint32_t iov_ui, uint8_t sapi, uint32_t lfn, uint32_t oc)
 
uint32_t gprs_cipher_gen_input_i (uint32_t iov_i, uint32_t lfn, uint32_t oc)
 
static __attribute__ ((constructor))
 

Variables

static struct gprs_cipher_impl * selected_ciphers [_GPRS_ALGO_NUM]
 
const struct value_string gprs_cipher_names []
 
static struct gprs_cipher_impl gea3_impl
 
static struct gprs_cipher_impl gea4_impl
 

Detailed Description

Osmocom GSM/GPRS ciphering algorithm implementation.

Function Documentation

void _a5_1 ( const uint8_t *  key,
uint32_t  fn,
ubit_t *  dl,
ubit_t *  ul 
)

Generate a GSM A5/1 cipher stream.

Parameters
[in]key8 byte array for the key (as received from the SIM)
[in]fnFrame number
[out]dlPointer to array of ubits to return Downlink cipher stream
[out]ulPointer to array of ubits to return Uplink cipher stream

Either (or both) of dl/ul can be NULL if not needed.

References _a5_1_clock(), _a5_1_get_output(), and osmo_a5_fn_count().

Referenced by osmo_a5().

static uint32_t _a5_12_clock ( uint32_t  r,
uint32_t  mask,
uint32_t  taps 
)
inlinestatic

Compute the next LFSR state.

Parameters
[in]rCurrent state
[in]maskLFSR mask
[in]tapsLFSR taps
Returns
Next state

References _a5_12_parity().

Referenced by _a5_1_clock(), and _a5_2_clock().

static uint32_t _a5_12_majority ( uint32_t  v1,
uint32_t  v2,
uint32_t  v3 
)
inlinestatic

Compute majority bit from 3 taps.

Parameters
[in]v1LFSR state ANDed with tap-bit
[in]v2LFSR state ANDed with tap-bit
[in]v3LFSR state ANDed with tap-bit
Returns
The majority bit (0 or 1)

Referenced by _a5_1_clock(), and _a5_2_get_output().

static uint32_t _a5_12_parity ( uint32_t  x)
inlinestatic

Computes parity of a 32-bit word.

Parameters
[in]x32 bit word
Returns
Parity bit (xor of all bits) as 0 or 1

Referenced by _a5_12_clock().

static void _a5_1_clock ( uint32_t  r[],
int  force 
)
inlinestatic

GSM A5/1 Clocking function.

Parameters
[in]rRegister state
[in]forceNon-zero value disable conditional clocking

References _a5_12_clock(), and _a5_12_majority().

Referenced by _a5_1().

static uint8_t _a5_1_get_output ( uint32_t  r[])
inlinestatic

GSM A5/1 Output function.

Parameters
[in]rRegister state
Returns
The A5/1 output function bit

Referenced by _a5_1().

void _a5_2 ( const uint8_t *  key,
uint32_t  fn,
ubit_t *  dl,
ubit_t *  ul 
)

Generate a GSM A5/1 cipher stream.

Parameters
[in]key8 byte array for the key (as received from the SIM)
[in]fnFrame number
[out]dlPointer to array of ubits to return Downlink cipher stream
[out]ulPointer to array of ubits to return Uplink cipher stream

Either (or both) of dl/ul can be NULL if not needed.

References _a5_2_clock(), _a5_2_get_output(), and osmo_a5_fn_count().

Referenced by osmo_a5().

static void _a5_2_clock ( uint32_t  r[],
int  force 
)
inlinestatic

GSM A5/2 Clocking function.

Parameters
[in]rRegister state
[in]forceNon-zero value disable conditional clocking

References _a5_12_clock().

Referenced by _a5_2().

static uint8_t _a5_2_get_output ( uint32_t  r[])
inlinestatic

GSM A5/2 Output function.

Parameters
[in]rRegister state
Returns
The A5/2 output function bit

References _a5_12_majority().

Referenced by _a5_2().

void _a5_3 ( const uint8_t *  key,
uint32_t  fn,
ubit_t *  dl,
ubit_t *  ul,
bool  fn_correct 
)

Generate a GSM A5/3 cipher stream.

Parameters
[in]key8 byte array for the key (as received from the SIM)
[in]fnFrame number
[out]dlPointer to array of ubits to return Downlink cipher stream
[out]ulPointer to array of ubits to return Uplink cipher stream
[in]fn_correcttrue if fn is a real GSM frame number and thus requires internal conversion

Either (or both) of dl/ul should be NULL if not needed.

Implementation based on specifications from 3GPP TS 55.216, 3GPP TR 55.919 and ETSI TS 135 202 with slight simplifications (CE hardcoded to 0).

References _a5_4().

Referenced by osmo_a5().

void _a5_4 ( const uint8_t *  ck,
uint32_t  fn,
ubit_t *  dl,
ubit_t *  ul,
bool  fn_correct 
)

Generate a GSM A5/4 cipher stream.

Parameters
[in]key16 byte array for the key (as received from the SIM)
[in]fnFrame number
[out]dlPointer to array of ubits to return Downlink cipher stream
[out]ulPointer to array of ubits to return Uplink cipher stream
[in]fn_correcttrue if fn is a real GSM frame number and thus requires internal conversion

Either (or both) of dl/ul should be NULL if not needed.

Implementation based on specifications from 3GPP TS 55.216, 3GPP TR 55.919 and ETSI TS 135 202 with slight simplifications (CE hardcoded to 0).

References osmo_a5_fn_count().

Referenced by _a5_3(), and osmo_a5().

int gea3 ( uint8_t *  out,
uint16_t  len,
uint8_t *  kc,
uint32_t  iv,
enum gprs_cipher_direction  direction 
)

Performs the GEA3 algorithm as in 3GPP TS 55.216 V6.2.0.

Parameters
[in,out]outBuffer for gamma for encrypted/decrypted
[in]lenLength of out, in bytes
[in]kcBuffer with the ciphering key
[in]ivInit vector
[in]directDirection: 0 (MS -> SGSN) or 1 (SGSN -> MS)

References gea4(), and gprs_cipher_key_length().

int gea4 ( uint8_t *  out,
uint16_t  len,
uint8_t *  kc,
uint32_t  iv,
enum gprs_cipher_direction  direction 
)

Performs the GEA4 algorithm as in 3GPP TS 55.226 V9.0.0.

Parameters
[in,out]outBuffer for gamma for encrypted/decrypted
[in]lenLength of out, in bytes
[in]kcBuffer with the ciphering key
[in]ivInit vector
[in]directDirection: 0 (MS -> SGSN) or 1 (SGSN -> MS)

Referenced by gea3().

unsigned gprs_cipher_key_length ( enum gprs_ciph_algo  algo)

Obtain key lenght for given GPRS cipher.

Parameters
[in]algoEnum representive GPRS cipher
Returns
unsigned integer key length for supported algorithms, for GEA0 and unknown ciphers will return 0

Referenced by gea3().

int osmo_a5 ( int  n,
const uint8_t *  key,
uint32_t  fn,
ubit_t *  dl,
ubit_t *  ul 
)

Main method to generate a A5/x cipher stream.

Parameters
[in]nWhich A5/x method to use
[in]key8 or 16 (for a5/4) byte array for the key (as received from the SIM)
[in]fnFrame number
[out]dlPointer to array of ubits to return Downlink cipher stream
[out]ulPointer to array of ubits to return Uplink cipher stream
Returns
0 for success, -ENOTSUP for invalid cipher selection.

Currently A5/[0-4] are supported. Either (or both) of dl/ul can be NULL if not needed.

References _a5_1(), _a5_2(), _a5_3(), and _a5_4().

Variable Documentation

struct gprs_cipher_impl gea3_impl
static
Initial value:
= {
.algo = GPRS_ALGO_GEA3,
.name = "GEA3 (libosmogsm built-in)",
.priority = 100,
.run = &gea3,
}
int gea3(uint8_t *out, uint16_t len, uint8_t *kc, uint32_t iv, enum gprs_cipher_direction direct)
Performs the GEA3 algorithm as in 3GPP TS 55.216 V6.2.0.
Definition: gea.c:61
struct gprs_cipher_impl gea4_impl
static
Initial value:
= {
.algo = GPRS_ALGO_GEA4,
.name = "GEA4 (libosmogsm built-in)",
.priority = 100,
.run = &gea4,
}
int gea4(uint8_t *out, uint16_t len, uint8_t *kc, uint32_t iv, enum gprs_cipher_direction direct)
Performs the GEA4 algorithm as in 3GPP TS 55.226 V9.0.0.
Definition: gea.c:47
const struct value_string gprs_cipher_names[]
Initial value:
= {
{ GPRS_ALGO_GEA0, "GEA0" },
{ GPRS_ALGO_GEA1, "GEA1" },
{ GPRS_ALGO_GEA2, "GEA2" },
{ GPRS_ALGO_GEA3, "GEA3" },
{ GPRS_ALGO_GEA4, "GEA4" },
{ 0, NULL },
}