From patchwork Thu Sep 24 11:44:06 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Neels Hofmeyr X-Patchwork-Id: 522248 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.osmocom.org (tmp.osmocom.org [144.76.43.76]) by ozlabs.org (Postfix) with ESMTP id 87D08140271 for ; Thu, 24 Sep 2015 21:45:36 +1000 (AEST) Received: from lists.osmocom.org (lists.osmocom.org [144.76.43.76]) by lists.osmocom.org (Postfix) with ESMTP id E06618059; Thu, 24 Sep 2015 11:45:34 +0000 (UTC) X-Original-To: openbsc@lists.osmocom.org Delivered-To: openbsc@lists.osmocom.org Received: from ganesha.gnumonks.org (ganesha.gnumonks.org [213.95.27.120]) by lists.osmocom.org (Postfix) with ESMTP id 5EF418047 for ; Thu, 24 Sep 2015 11:45:33 +0000 (UTC) Received: from mail.sysmocom.de ([144.76.43.93]) by ganesha.gnumonks.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.72) (envelope-from ) id 1Zf4xv-000609-6k for openbsc@lists.osmocom.org; Thu, 24 Sep 2015 13:45:33 +0200 Received: from dub5.am93.sysmocom.de (ip5b4185b8.dynamic.kabel-deutschland.de [91.65.133.184]) by mail.sysmocom.de (Postfix) with ESMTPSA id 2B3951B0C1A for ; Thu, 24 Sep 2015 11:44:59 +0000 (UTC) From: Neels Hofmeyr To: openbsc@lists.osmocom.org Subject: [PATCH 1/3] Add initial OAP protocol design document Date: Thu, 24 Sep 2015 13:44:06 +0200 Message-Id: <1443095048-4593-1-git-send-email-nhofmeyr@sysmocom.de> X-Mailer: git-send-email 2.1.4 X-Spam-Score: 0.1 (/) X-Spam-Report: SpamASsassin versoin 3.3.1 on ganesha.gnumonks.org summary: Content analysis details: (0.1 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 2.7 DNS_FROM_AHBL_RHSBL RBL: Envelope sender listed in dnsbl.ahbl.org -0.7 RCVD_IN_DNSWL_LOW RBL: Sender listed at http://www.dnswl.org/, low trust [144.76.43.93 listed in list.dnswl.org] -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0029] X-BeenThere: openbsc@lists.osmocom.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: Development of the OpenBSC GSM base station controller List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: openbsc-bounces@lists.osmocom.org Sender: "OpenBSC" Sponsored-by: On-Waves ehf --- openbsc/doc/osmocom-authn-protocol.txt | 191 +++++++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 openbsc/doc/osmocom-authn-protocol.txt diff --git a/openbsc/doc/osmocom-authn-protocol.txt b/openbsc/doc/osmocom-authn-protocol.txt new file mode 100644 index 0000000..660fdb6 --- /dev/null +++ b/openbsc/doc/osmocom-authn-protocol.txt @@ -0,0 +1,191 @@ + + Osmocom Authentication Protocol (OAP) + +1. General + +This document describes the remote protocol that is used by the SGSN and MAP +proxy to authenticate each other. The protocol and the messages are designed +after the corresponding MAP messages (see GSM 09.02) with the following +differences: + + - The encoding uses TLV structures instead of ASN.1 encodings + - Segmentation is not used + +See the specification of the Gr interface (GSM 03.60). + +1.1. Connection + +The protocol expects that a reliable, ordered, packet boundaries preserving +connection is used (e.g. IPA over TCP). The remote peer is either a service +that understands the protocol natively or a wrapper service that maps the +messages to/from real MAP messages that can be used to directly communicate +with an HLR. + +1.2. Using IPA + +By default, the following identifiers should be used: + - IPA protocol: 0xee (OSMO) + - IPA OSMO protocol extension: 0x06 + +2. Procedures + +Ideal communication sequence: + + SGSN MAP + | | + | Register (Id) | + |----------------------------------->| + | | + | Challenge (RAND+AUTN) | + |<-----------------------------------| + | | + | Challenge Result (SRES) | + |----------------------------------->| + | | + | Register Result | + |<-----------------------------------| + +2.1. Register + +The SGSN sends a REGISTER_REQ message containing an SGSN identifier number. + +2.2. Challenge + +The OAP server (optionally) sends a CHALLENGE_REQ to the SGSN, containing +random bytes and a milenage authentication token generated from these random +bytes, using a shared secret, to authenticate itself to the OAP client (SGSN). +The server may omit this challenge entirely, based on its configuration, and +immediately reply with a Register Result response. If the SGSN cannot be +registered (e.g. id is invalid), the server sends a REGISTER_ERR response. + +2.3. Challenge Result + +When the SGSN has received a Challenge, it may verify the server's +authenticity, and reply with a CHALLENGE_RES message. This shall contain SRES +(and Kc?) authentication tokens generated by milenage from the same random +bytes received from the server and the same shared secet. If the SGSN cannot +verify the server's authenticity, it shall instead send a CHALLENGE_ERR +message. + +2.4. Register Result + +The MAP sends a REGISTER_RES message to indicate that registration has been +successful. If the MAP proxy cannot register the SGSN (e.g. invalid challenge +response), it sends a REGISTER_ERR message. + +3. Message Format + +3.1. General + +Every message is based on the following message format + + IEI Info Element Type Pres. Format Length + Message type 4.2.1 M V 1 + +The receiver shall be able to receive IEs in any order. Unknown IEs shall be +ignored. + +3.2.1. Register Request + +SGSN -> Network peer + + IEI Info Element Type Pres. Format Length + Message type 4.2.1 M V 1 + 30 SGSN Id big endian int (2 oct) M TLV 4 + +3.2.2. Register Error + +Network peer -> SGSN + + IEI Info Element Type Pres. Format Length + Message type 4.2.1 M V 1 + 02 Cause GMM cause, M TLV 3 + 04.08: 10.5.5.14 + +3.2.6. Register Result + +Network peer -> SGSN + + IEI Info Element Type Pres. Format Length + Message type 4.2.1 M V 1 + +3.2.3. Challenge + +Network peer -> SGSN + + IEI Info Element Type Pres. Format Length + Message type 4.2.1 M V 1 + 20 RAND octet string (16) M TLV 18 + 23 AUTN octet string (16) M TLV 18 + +3.2.4. Challenge Error + +SGSN -> Network peer + + IEI Info Element Type Pres. Format Length + Message type 4.2.1 M V 1 + 02 Cause GMM cause, M TLV 3 + 04.08: 10.5.5.14 + +3.2.5. Challenge Result + +SGSN -> Network peer + + IEI Info Element Type Pres. Format Length + Message type 4.2.1 M V 1 + 21 SRES octet string (4) M TLV 6 + 22 Kc octet string (8) M TLV 10 + +4. Information Elements + +4.1. General + +[...] + +4.2.1. Message Type + + +---------------------------------------------------+ + | 8 7 6 5 4 3 2 1 | + | | + | 0 0 0 0 0 1 0 0 - Register Request | + | 0 0 0 0 0 1 0 1 - Register Error | + | 0 0 0 0 0 1 1 0 - Register Result | + | | + | 0 0 0 0 1 0 0 0 - Challenge Request | + | 0 0 0 0 1 0 0 1 - Challenge Error | + | 0 0 0 0 1 0 1 0 - Challenge Result | + | | + +---------------------------------------------------+ + +4.2.2. IE Identifier (informational) + +These are the standard values for the IEI. + + +---------------------------------------------------------+ + | IEI Info Element Type | + | | + | 0x02 Cause GMM cause, 04.08: 10.5.5.14 | + | 0x20 RAND octet string | + | 0x21 SRES octet string | + | 0x22 Kc octet string | + | 0x23 AUTN octet string | + | 0x30 SGSN Id big endian int (2 octets) | + +---------------------------------------------------------+ + +4.2.3. SGSN Id + + 8 7 6 5 4 3 2 1 + +-----------------------------------------------------+ + | | SGSN Id IEI | octet 1 + +-----------------------------------------------------+ + | Length of SGSN Id IE contents (2) | octet 2 + +-----------------------------------------------------+ + | SGSN Id number, most significant byte | octet 3 + +-----------------------------------------------------+ + | SGSN Id number, least significant byte | octet 4 + +-----------------------------------------------------+ + +The SGSN Id number shall be interpreted as an unsigned 16bit integer, where 0 +indicates an invalid / unset Id. + +