[sim-auth PATCH 0/5] SIM Authentication D-Bus API

[sim-auth PATCH 0/5] SIM Authentication D-Bus API

[Pekka.Pessi]

[-- Attachment #1: Type: text/plain, Size: 882 bytes --]

From: Pekka Pessi <Pekka.Pessi@nokia.com>

Hi all,

Here is my proposed SIM authentication API, marked as experimental.

First two patches are hopefully easy to swallow. The uglier GBA_U part
and some generic GBA blather can be found in last three patches.

Unfortunately the IMS support requires GBA_U.

--Pekka

Pekka Pessi (5):
  Add doc/sim-authentication-api.txt
  Add doc/sim-authentication-api.txt to dist
  Add GBA_U to SIM authentication API
  Add doc/gba-authentication.txt
  Add doc/gba-authentication.txt to dist

 Makefile.am                    |    5 +-
 doc/gba-authentication.txt     |   70 ++++++++++++++++
 doc/sim-authentication-api.txt |  171 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 244 insertions(+), 2 deletions(-)
 create mode 100644 doc/gba-authentication.txt
 create mode 100644 doc/sim-authentication-api.txt

[sim-auth PATCH 1/5] Add doc/sim-authentication-api.txt

[Pekka.Pessi]

[-- Attachment #1: Type: text/plain, Size: 2938 bytes --]

From: Pekka Pessi <Pekka.Pessi@nokia.com>

The authentication suites include SIM authentication (basic A8
authentication used with GSM) and AKA authentication on USIM.

The SIM and AKA can be used to implement EAP, AKA Digest and GBA
authentication algorithms.
---
 doc/sim-authentication-api.txt |   81 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 81 insertions(+), 0 deletions(-)
 create mode 100644 doc/sim-authentication-api.txt

diff --git a/doc/sim-authentication-api.txt b/doc/sim-authentication-api.txt
new file mode 100644
index 0000000..27090e7
--- /dev/null
+++ b/doc/sim-authentication-api.txt
@@ -0,0 +1,81 @@
+SimAuthentication hierarchy [experimental]
+==========================================
+
+Service		org.ofono
+Interface	org.ofono.SimAuthentication
+Object path	[variable prefix]/{modem0,modem1,...}
+
+Methods		dict GetProperties()
+
+			Returns all properties for this object. See the
+			properties section for available properties.
+
+		dict Authenticate(string suite, dict input)
+
+			Executes the requested authentication suite.
+			The input and returned result depend on the
+			authentication suite.
+
+			See the suite sections for input and results for
+			each suite.
+
+			Possible Errors: [service].Error.InvalidArguments
+					 [service].Error.NotImplemented
+
+Properties	array{string} Suites [readonly]
+
+			Contains the list of supported authentication
+			suites and applications. The possible values are:
+
+			"SIM" - SIM authentication
+			"AKA" - AKA authentication
+
+SIM Authentication Suite
+------------------------
+
+		SIM authentication (A8) can be used to implement EAP SIM
+		or 2G GBA authentication.
+
+		In case of successful SIM authentication the returned
+		dictionary contains following items:
+
+			byte{array} "SRES" - SRES parameter
+
+			byte{array} "Kc" - Kc ciphering key
+
+		The RAND parameter is a 16-byte array.
+
+		The SRES parameter is a 4-byte array.
+
+		The Kc parameter is a 8-byte array.
+
+AKA Authentication Suite
+------------------------
+
+		AKA authentication can be used to implement EAP AKA, AKA
+		digest or GBA_ME authentication.
+
+		The input dictionary must contain following input
+		parameters:
+
+			byte{array} "RAND" - RAND parameter
+
+			byte{array} "AUTN" - AUTN parameter
+
+		In case of successful AKA authentication the returned
+		dictionary contains following items:
+
+			byte{array} "RES" - AKA RES parameter
+
+			byte{array} "CK" - AKA Ciphering key
+
+			byte{array} "IK" - AKA Integrity key
+
+		AKA is a mutual authentication algorithm: terminal and
+		network authenticate each other. In case the terminal
+		rejects the AUTN from network, the returned dictionary
+		contains following item:
+
+			byte{array} "AUTS" - AKA AUTS parameter
+
+		All the AKA parameters and keys are 16-byte arrays.
-- 
1.7.1

[sim-auth PATCH 2/5] Add doc/sim-authentication-api.txt to dist

[Pekka.Pessi]

[-- Attachment #1: Type: text/plain, Size: 620 bytes --]

From: Pekka Pessi <Pekka.Pessi@nokia.com>

---
 Makefile.am |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)

diff --git a/Makefile.am b/Makefile.am
index c1c34ca..65b488a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -394,6 +394,7 @@ doc_files = doc/overview.txt doc/ofono-paper.txt doc/release-faq.txt \
 			doc/message-api.txt doc/message-waiting-api.txt \
 			doc/phonebook-api.txt doc/radio-settings-api.txt \
 			doc/sim-api.txt doc/stk-api.txt \
+			doc/sim-authentication-api.txt \
 			doc/audio-settings-api.txt doc/text-telephony-api.txt \
 			doc/calypso-modem.txt
 
-- 
1.7.1

[sim-auth PATCH 3/5] Add GBA_U to SIM authentication API

[Pekka.Pessi]

[-- Attachment #1: Type: text/plain, Size: 3589 bytes --]

From: Pekka Pessi <Pekka.Pessi@nokia.com>

---
 doc/sim-authentication-api.txt |   90 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 90 insertions(+), 0 deletions(-)

diff --git a/doc/sim-authentication-api.txt b/doc/sim-authentication-api.txt
index 27090e7..2db80bb 100644
--- a/doc/sim-authentication-api.txt
+++ b/doc/sim-authentication-api.txt
@@ -29,6 +29,7 @@ Properties	array{string} Suites [readonly]
 
 			"SIM" - SIM authentication
 			"AKA" - AKA authentication
+			"GBA_U" - UICC-based GBA authentication
 
 SIM Authentication Suite
 ------------------------
@@ -36,6 +37,11 @@ SIM Authentication Suite
 		SIM authentication (A8) can be used to implement EAP SIM
 		or 2G GBA authentication.
 
+		The input dictionary must contain following input
+		parameters:
+
+			byte{array} "RAND" - RAND parameter
+
 		In case of successful SIM authentication the returned
 		dictionary contains following items:
 
@@ -79,3 +85,87 @@ AKA Authentication Suite
 			byte{array} "AUTS" - AKA AUTS parameter
 
 		All the AKA parameters and keys are 16-byte arrays.
+
+GBA_U Suite
+-----------
+
+		GBA_U is a GBA variant used if USIM or ISIM application
+		supports it.
+
+		The GBA_U authentication suite has three different
+		operations:
+
+		- bootstrapping (AKA authentication with BSF)
+		- update (storing result from BSF to SIM)
+		- NAF key derivation
+
+		The GBA suite recognizes the operations based on the
+		input parameters.
+
+GBA Bootstrapping
+
+		The GBA bootstrapping authentication is done after
+		receiving AKA challenge from bootstrap server (BSF).
+		After successful authentication, SIM will store the RAND
+		and the Ks for further use.
+
+		The input dictionary for the GBA bootstrapping must
+		contain following parameters:
+
+			byte{array} "RAND" - AKA RAND parameter
+
+			byte{array} "AUTN" - AKA AUTN parameter
+
+		In case of successful initial GBA bootstrapping the
+		returned dictionary contains following items:
+
+			byte{array} "RES" - AKA RES parameter
+
+		In case of unsuccessful bootstrapping the returned
+		dictionary contains following item:
+
+			byte{array} "AUTS" - AKA AUTS parameter
+
+GBA Update
+
+		If the bootstrap operation is successful, the "btid" and
+		"lifetime" parameters received from bootstrap server
+		should be stored on the SIM card. The "btid" parameter
+		will be used as user identity with NAF servers.
+
+		The input dictionary for GBA update must contain
+		following parameters:
+
+			string "btid" - B-TID parameter
+			string "lifetime" - expected lifetime of Ks key
+
+		In case of successful update, an empty dictionary is
+		returned.
+
+NAF Key Derivation
+
+		The NAF key is used to authenticate mobile with a server
+		using GBA.
+
+		The input dictionary for NAF key derivation must contain
+		the following parameters:
+
+			string "name" - NAF domain name
+
+			byte{array} "protocol" - security protocol identifier
+
+		The security protocol identifier is usually a 5 byte
+		array. It indicates the protocol used between the mobile
+		device (UE) and the network server (NAF).  See 3GPP TS
+		33.220 Annex H for protocol identifiers.
+
+		In case of successful NAF key derivation the returned
+		dictionary contains following item:
+
+			byte{array} "KS-NAF" - KS_ext_NAF key
+
+		The KS-NAF is a 32-byte array.
+
+		The applications running on SIM can use GBA_U to derive
+		so called KS_int_NAF keys, however, they are not
+		accessible outside SIM card.
-- 
1.7.1

[sim-auth PATCH 4/5] Add doc/gba-authentication.txt

[Pekka.Pessi]

[-- Attachment #1: Type: text/plain, Size: 3243 bytes --]

From: Pekka Pessi <Pekka.Pessi@nokia.com>

---
 doc/gba-authentication.txt |   70 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 70 insertions(+), 0 deletions(-)
 create mode 100644 doc/gba-authentication.txt

diff --git a/doc/gba-authentication.txt b/doc/gba-authentication.txt
new file mode 100644
index 0000000..4c88ace
--- /dev/null
+++ b/doc/gba-authentication.txt
@@ -0,0 +1,70 @@
+GBA Authentication
+==================
+
+		GBA authentication uses SIM card to establish a unique
+		identity and a shared secret for a network service.  The
+		shared secret is computed from the domain name of the
+		service and a special boostrap key, Ks.
+
+		GBA is used to authenticate the mobile with the IMS XCAP
+		servers.
+
+		The mobile obtains the bootstrap key and a temporary
+		identity used with network services from a special
+		boostraps bootstrap server, BSF.  Mobile authenticates
+		itself with BSF using AKA authentication and the BSF
+		returns it the identity to use with network services
+		(known as NAF). The bootstrap key is formed from the AKA
+		authentication results, too.
+
+		In the initial phase the client will send its user
+		identity, the IP Multimedia Private Identity (IMPI) to
+		the BSF server. The BSF server fetches an AKA challenge
+		from operator's subscriber database along with correct
+		response: RAND, AUTN, XRES, CK and IK.  Server returns
+		the AKA challenge RAND and AUTN to mobile.
+
+		The client uses SIM to calculate the AKA RES, CK and IK
+		from the challenge, and uses RES to generate AKA Digest
+		credentials sent back to the bootstrap server.
+
+		The bootstrapping server verifies the response using
+		XRES, and if accepted, it will return an XML document
+		containing the bootstrapping transaction identifier
+		(B-TID) and the lifetime of the KS_NAF keys.
+
+		The CK and IK parameters from AKA authentication are
+		used for Ks.  The Ks can now be used to derive unique
+		key for each NSF service.
+
+		For further reference on GBA, see 3GPP TS 33.220
+		and 3GPP TS 24.109.
+
+GBA Variants
+------------
+
+		There are three different GBA variants: 2G GBA, GBA_ME
+		and GBA_U. The variant is selected based on SIM card
+		capabilities.The 2G GBA is used if there is no 3G USIM
+		available. The GBA_ME is used if there is USIM or ISIM
+		application on SIM card (also known as UICC), but there
+		is no support for GBA service.
+
+		In the GBA_ME variant the Ks key is stored outside SIM
+		card. It is implemented using ordinary AKA
+		authentication.
+
+		In the 2G variant, there is no AKA authentication, but
+		it is rather simulated using 2G A8 SIM authentication
+		algorithm. The 2G variant is described in the 3GPP
+		33.220 Annex I.
+
+		The UICC-based GBA variant, GBA_U, keeps the Ks key
+		stored on the SIM card (UICC) and lets the SIM card
+		calculate the NAF keys.
+
+		Note that the device cannot downgrade the protocol:
+		subscriber database has recorded if the SIM card
+		supports GBA_U andthe information is included in the AKA
+		challenge. The SIM card will reject a GBA_U-related AKA
+		challenge if it is used with ordinary AKA service.
-- 
1.7.1

[sim-auth PATCH 5/5] Add doc/gba-authentication.txt to dist

[Pekka.Pessi]

[-- Attachment #1: Type: text/plain, Size: 645 bytes --]

From: Pekka Pessi <Pekka.Pessi@nokia.com>

---
 Makefile.am |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Makefile.am b/Makefile.am
index 65b488a..462b05f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -396,8 +396,8 @@ doc_files = doc/overview.txt doc/ofono-paper.txt doc/release-faq.txt \
 			doc/sim-api.txt doc/stk-api.txt \
 			doc/sim-authentication-api.txt \
 			doc/audio-settings-api.txt doc/text-telephony-api.txt \
-			doc/calypso-modem.txt
-
+			doc/calypso-modem.txt \
+			doc/gba-authentication.txt
 
 test_scripts = test/backtrace \
 		test/create-internet-context \
-- 
1.7.1

Re: [sim-auth PATCH 4/5] Add doc/gba-authentication.txt

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 503 bytes --]

Hi Pekka,

On 01/20/2011 10:53 AM, Pekka.Pessi(a)nokia.com wrote:
> From: Pekka Pessi <Pekka.Pessi@nokia.com>
> 
> ---
>  doc/gba-authentication.txt |   70 ++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 70 insertions(+), 0 deletions(-)
>  create mode 100644 doc/gba-authentication.txt
> 

Can you do me a favor and reflow this document a bit? Right now you're
using two tab indentation unnecessarily.

It is also fine to squash patch 4 & 5 together.

Regards,
-Denis