Open Source IMS Client

h1. AKA socket SIM interface

{{>toc}}

This is an interface we are creating to communicate the 3G-AKA (authentication and key agreement) between clients (consumders) and servers (providers)

A _provider_ interfaces in some way with a USIM card, for example

* via pcsc-lite to a USIM inserted in a CCID reader

* via AT-commands (AT+CSIM) to a USIM inserted in a cellular modem

A _consumer_ interfaces in some wayt with a 3GPP cellular network, for example

* [[doubango]] when authenticating against an IMS Core (P-CSCF) in [[VoLTE]] and [[VoWiFi]]

* strongswan IPsec client when establishing the SWu interface towards the ePDG in [[VoWiFi]]

It could possibly also be used by other projects like srsUE, OsmocomBB, ...

h2. Protocol / Data structures

The interface is based on a unix domain socke with a very simplistic binary message format as outlined below:

<pre>

#pragma once

/* Definitions regarding the "AKA authentication socket", a mechanism

 * by which various client programs can request the 3G AKA procedure to be performed

 * against a card.

 *

 * This is intended as a very simple, low-level interface.  Security/access control is

 * managed by file system permissions, i.e. which processes can access the unix domain

 * socket path.

 *

 * (C) 2022 by Harald Welte <laforge@osmocom.org>

 */

#include <stdint.h>

#define AKASOCK_MAGIC           0x51FC43D5

#define AKASOCK_VERSION         1

enum akasock_msg_type {

        AKASOCK_MSGT_AKA_REQ            = 0x01,

        AKASOCK_MSGT_AKA_RES_OK         = 0x02,

        AKASOCK_MSGT_AKA_RES_SYNC       = 0x03,

        AKASOCK_MSGT_AKA_RES_ERR        = 0x04,

        AKASOCK_MSGT_IMSI_REQ           = 0x05,

        AKASOCK_MSGT_IMSI_RES           = 0x06,

};

struct akasock_msg_hdr {

        uint32_t magic;         /* AKASOCK_MAGIC */

        uint8_t version;        /* AKASOCK_VERSION */

        uint8_t msg_type;       /* akasock_msg_type */

        uint8_t channel;        /* 0=first SIM, 1=2nd, ... */

        uint8_t tag;            /* to match request with response */

        uint8_t data[0];        /* any of the structs below */

} __attribute__ ((packed));

struct akasock_aka_req {

        uint8_t isim_instead_of_usim; /* 0=USIM, 1=ISIM */

        uint8_t rand_len;

        uint8_t rand[32];

        uint8_t autn_len;

        uint8_t autn[32];

} __attribute__ ((packed));

struct akasock_aka_resp_success {

        uint8_t res_len;

        uint8_t res[32];

        uint8_t ck_len;

        uint8_t ck[32];

        uint8_t ik_len;

        uint8_t ik[32];

        uint8_t kc_len;

        uint8_t kc[32];

} __attribute__ ((packed));

struct akasock_aka_resp_sync {

        uint8_t auts_len;

        uint8_t auts[32];

} __attribute__ ((packed));

struct akasock_aka_resp_err {

        uint16_t sw;

} __attribute__ ((packed));

struct akasock_imsi_resp {

        uint8_t imsi_len;

        char imsi[32];          /* IMSI As ASCII string */

} __attribute__ ((packed));

</pre>

h2. Message flow

The client programs (doubango, strongswan, ...) will typically perform the following exchanges:

{{mscgen_link

msc {

  hscale=2;

  pcscf [label="P-CSCF"], client [label="AKASOCK client (e.g. doubango)"], server [label="AKASOCK server"], sim [label="SIM card"];

  client => server [label="AKASOCK_MSGT_IMSI_REQ"];

  server => sim [label="SELECT ADF.USIM/EF.IMSI"];

  server => sim [label="READ BINARY"];

  server box server [label="convert from binary to string"];

  client <= server [label="AKASOCK_MSGT_IMSI_RES"];

  client box client [label="Client can now start first SIP REGISTER with IPUI=IMSI"];

  pcscf <= client [label="SIP REGISTER (first one)"];

  pcscf => client [label="Unauthorized (contains RAND,AUTN)"];

  client => server [label="AKASOCK_MSGT_AKA_REQ (RAND, AUTN)"];

  client => sim [label="AUTHENTICATE"];

  client <= sim [label="Result"];

  client <= server [label="AKASOCK_MSGT_AKA_RES_OK (RES, CK, IK)"];

  client box client [label="Derive IPsec keys from CK, IK, create SAs"];

  pcscf <= client [label="Start new TCP connection inside IPsec SA"];

  pcscf <= client [label="SIP REGISTER (second, with RES)"];

  pcscf box pcscf [label="Verify RES"];

  pcscf => client [label="200 OK"];

}

}}

AKA socket