cellular-infrastructure
/
osmo-bsc
mirror of https://gerrit.osmocom.org/osmo-bsc
9
0
Fork 0
Code Issues Releases Wiki Activity

remove old copy of documentation that now is in osmo-gsm-manuals.git 

We keep some random snippets of documentation here, but manuals are now
generally kept in osmo-gsm-manuals.git.  Particularly the GSUP, OAP and
control interface are documented more extensively there.

To avoid having two sets of (diverging) documentation, let's remove it
from the openbsc.git repository.

Change-Id: I4a4c918587e236a7aa00cf2bb6aa05b090f7229b
This commit is contained in:
Harald Welte 2016-07-23 14:00:40 +02:00 committed by Neels Hofmeyr
parent 14314bd808
commit 7c989e7ced
3 changed files with 0 additions and 739 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
openbsc/doc/control-interface.txt
View File

@ -1,21 +0,0 @@
The protocol for the control interface is wrapped inside the ip.access header
with the IPAC_PROTO_OSMO protocol ID (0xee). Inside the ip.access header is
a struct ipaccess_head_ext with protocol ID 0x00 which indicates the control
interface.
After that the actual protocol is text based:
* Getting the value of a variable
-> GET <id> <var>
<- GET_REPLY <id> <var> <val>
or ERROR <id> <reason>
* Setting the value of a variable
-> SET <id> <var> <val>
<- SET_REPLY <id> <var> <val>
or ERROR <id> <reason>
* A value changes which triggers a trap
<- TRAP <var> <val>
<id> needs to be unique within a connection. '0' is not allowed

250
openbsc/doc/osmocom-authn-protocol.txt
View File

@ -1,250 +0,0 @@
Osmocom Authentication Protocol (OAP)
1. General
The Osmocom Authentication Protocol employs mutual authentication to register a
client with a server over an IPA connection. Milenage is used as the
authentication algorithm, where client and server have a shared secret.
For example, an SGSN, as OAP client, may use its SGSN ID to register with a MAP
proxy, an OAP server.
1.1. Connection
The protocol expects that a reliable, ordered, packet boundaries preserving
connection is used (e.g. IPA over TCP).
1.2. Using IPA
By default, the following identifiers should be used:
- IPA protocol: 0xee (OSMO)
- IPA OSMO protocol extension: 0x06 (OAP)
2. Procedures
Ideal communication sequence:
Client Server
| |
| Register (ID) |
|----------------------------------->|
| |
| Challenge (RAND+AUTN) |
|<-----------------------------------|
| |
| Challenge Result (XRES) |
|----------------------------------->|
| |
| Register Result |
|<-----------------------------------|
Variation "test setup":
Client Server
| |
| Register (ID) |
|----------------------------------->|
| |
| Register Result |
|<-----------------------------------|
Variation "invalid sequence nr":
Client Server
| |
| Register (ID) |
|----------------------------------->|
| |
| Challenge (RAND+AUTN) |
|<-----------------------------------|
| |
| Sync Request (AUTS) |
|----------------------------------->|
| |
| Challenge (RAND'+AUTN') |
|<-----------------------------------|
| |
| Challenge Result (XRES) |
|----------------------------------->|
| |
| Register Result |
|<-----------------------------------|
2.1. Register
The client sends a REGISTER_REQ message containing an identifier number.
2.2. Challenge
The OAP server (optionally) sends back a CHALLENGE_REQ, containing random bytes
and a milenage authentication token generated from these random bytes, using a
shared secret, to authenticate itself to the OAP client. The server may omit
this challenge entirely, based on its configuration, and immediately reply with
a Register Result response. If the client cannot be registered (e.g. id is
invalid), the server sends a REGISTER_ERR response.
2.3. Challenge Result
When the client has received a Challenge, it may verify the server's
authenticity and validity of the sequence number (included in AUTN), and, if
valid, reply with a CHALLENGE_RES message. This shall contain an XRES
authentication token generated by milenage from the same random bytes received
from the server and the same shared secet. If the client decides to cancel the
registration (e.g. invalid AUTN), it shall not reply to the CHALLENGE_REQ; a
CHALLENGE_ERR message may be sent, but is not mandatory. For example, the
client may directly start with a new REGISTER_REQ message.
2.4. Sync Request
When the client has received a Challenge but sees an invalid sequence number
(embedded in AUTN, according to the milenage algorithm), the client may send a
SYNC_REQ message containing an AUTS synchronisation token.
2.5. Sync Result
If the server has received a valid Sync Request, it shall answer by directly
sending another Challenge (see 2.2.). If an invalid Sync Request is received,
the server shall reply with a REGISTER_ERR message.
2.6. Register Result
The server sends a REGISTER_RES message to indicate that registration has been
successful. If the server cannot register the client (e.g. invalid challenge
response), it shall send 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
Client -> Server
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
30 Client ID big endian int (2 oct) M TLV 4
3.2.2. Register Error
Server -> Client
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
Server -> Client
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
3.2.3. Challenge
Server -> Client
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
Client -> Server
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
Client -> Server
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
21 XRES octet string (8) M TLV 10
3.2.3. Sync Request
Client -> Server
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
20 AUTS octet string (16) M TLV 18
3.2.4. Sync Error
Server -> Client
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
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 |
| |
| 0 0 0 0 1 1 0 0 - Sync Request |
| 0 0 0 0 1 1 0 1 - Sync Error (not used) |
| 0 0 0 0 1 1 1 0 - Sync Result (not used) |
| |
+---------------------------------------------------+
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 |
| 0x23 AUTN octet string |
| 0x24 XRES octet string |
| 0x25 AUTS octet string |
| 0x30 Client ID big endian int (2 octets) |
+---------------------------------------------------------+
4.2.3. Client ID
8 7 6 5 4 3 2 1
+-----------------------------------------------------+
| | Client ID IEI | octet 1
+-----------------------------------------------------+
| Length of Client ID IE contents (2) | octet 2
+-----------------------------------------------------+
| Client ID number, most significant byte | octet 3
+-----------------------------------------------------+
| Client ID number, least significant byte | octet 4
+-----------------------------------------------------+
The Client ID number shall be interpreted as an unsigned 16bit integer, where 0
indicates an invalid / unset ID.

468
openbsc/doc/sgsn-remote-protocol.txt
View File

@ -1,468 +0,0 @@
GPRS Subscriber Update Protocol
1. General
This document describes the remote protocol that is used by the SGSN to update
and manage the local subscriber list. 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).
2. 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.
2.1. Using IPA
By default, the following identifiers should be used:
- IPA protocol: 0xee (OSMO)
- IPA OSMO protocol extension: 0x05
2. Procedures
2.1. Authentication management
The SGSN sends a SEND_AUTHENTICATION_INFO_REQ message containing the MS's IMSI
to the peer. On errors, especially if authentication info is not availabe for
that IMSI, the peer returns a SEND_AUTHENTICATION_INFO_ERR message. Otherwise
the peer returns a SEND_AUTHENTICATION_INFO_RES message. If this message
contains at least one authentication tuple, the SGSN replaces all tuples that
are assigned to the subscriber. If the message doesn't contain any tuple the
SGSN may reject the Attach Request. (see GSM 09.02, 25.5.6)
2.2. Location Updating
The SGSN sends a UPDATE_LOCATION_REQ to the peer. If the request is denied by
the network, the peer returns an UPDATE_LOCATION_ERR message to the SGSN.
Otherwise the peer returns an UPDATE_LOCATION_RES message containing all
information fields that shall be inserted into the subscriber record. If
the 'PDP info complete' information element is set in the message, the SGSN
clears existing PDP information fields in the subscriber record first.
(see GSM 09.02, 19.1.1.8)
[...]
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
01 IMSI 4.2.9 M TLV 2-10
If a numeric range is indicated in the 'presence' column, multiple information
elements with the same tag may be used in sequence. The information elements
shall be sent in the given order. Nevertheless after the generic part the
receiver shall be able to received them in any order. Unknown IE shall be
ignored.
3.2.1. Send Authentication Info Request
SGSN -> Network peer
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
3.2.2. Send Authentication Info Error
Network peer -> SGSN
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
02 Cause GMM cause, M TLV 3
04.08: 10.5.5.14
3.2.3. Send Authentication Info Response
Network peer -> SGSN
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
03 Auth tuple 4.2.5 0-5 TLV 36
3.2.4. Update Location Request
SGSN -> Network peer
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
3.2.5. Update Location Error
Network peer -> SGSN
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
02 Cause GMM cause, M TLV 3
04.08: 10.5.5.14
3.2.6. Update Location Result
Network peer -> SGSN
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
08 MSISDN 4.2.10 O TLV 0-9
09 HLR Number 4.2.12 O TLV 0-9
04 PDP info complete 4.2.8 O TLV 2
05 PDP info 4.2.3 1-10 TLV
If the PDP info complete IE is present, the old PDP info list shall be cleared.
3.2.7. Location Cancellation Request
Network peer -> SGSN
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
06 Cancellation type 4.2.6 M TLV 3
3.2.8. Location Cancellation Result
SGSN -> Network peer
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
3.2.9. Purge MS Request
SGSN -> Network peer
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
09 HLR Number 4.2.12 M TLV 0-9
3.2.10. Purge MS Error
Network peer -> SGSN
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
02 Cause GMM cause, M TLV 3
04.08: 10.5.5.14
3.2.11. Purge MS Result
Network peer -> SGSN
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
07 Freeze P-TMSI 4.2.8 O TLV 2
3.2.12. Insert Subscriber Data Request
Network peer -> SGSN
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
04 PDP info complete 4.2.8 O TLV 2
05 PDP info 4.2.3 0-10 TLV
If the PDP info complete IE is present, the old PDP info list shall be cleared.
3.2.13. Insert Subscriber Data Error
SGSN -> Network peer
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
02 Cause GMM cause, M TLV 3
04.08: 10.5.5.14
3.2.14. Insert Subscriber Data Result
SGSN -> Network peer
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
3.2.15. Delete Subscriber Data Request
Network peer -> SGSN
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
10 PDP context id 4.2.3 0-10 TLV
(no conditional IE)
3.2.16. Delete Subscriber Data Error
SGSN -> Network peer
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-10
02 Cause GMM cause, M TLV 3
04.08: 10.5.5.14
3.2.17. Delete Subscriber Data Result
Network peer -> SGSN
IEI Info Element Type Pres. Format Length
Message type 4.2.1 M V 1
01 IMSI 4.2.9 M TLV 2-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 - Update Location Request |
| 0 0 0 0 0 1 0 1 - Update Location Error |
| 0 0 0 0 0 1 1 0 - Update Location Result |
| |
| 0 0 0 0 1 0 0 0 - Send Auth Info Request |
| 0 0 0 0 1 0 0 1 - Send Auth Info Error |
| 0 0 0 0 1 0 1 0 - Send Auth Info Result |
| |
| 0 0 0 0 1 1 0 0 - Purge MS Request |
| 0 0 0 0 1 1 0 1 - Purge MS Error |
| 0 0 0 0 1 1 1 0 - Purge MS Result |
| |
| 0 0 0 1 0 0 0 0 - Insert Subscr. Data Request |
| 0 0 0 1 0 0 0 1 - Insert Subscr. Data Error |
| 0 0 0 1 0 0 1 0 - Insert Subscr. Data Result |
| |
| 0 0 0 1 0 1 0 0 - Delete Subscr. Data Request |
| 0 0 0 1 0 1 0 1 - Delete Subscr. Data Error |
| 0 0 0 1 0 1 1 0 - Delete Subscr. Data Result |
| |
| 0 0 0 1 1 1 0 0 - Location Cancellation Request |
| 0 0 0 1 1 1 0 1 - Location Cancellation Error |
| 0 0 0 1 1 1 1 0 - Location Cancellation Result |
| |
+---------------------------------------------------+
4.2.2. IP Address
The value part is encoded like in the Packet data protocol address IE defined
in GSM 04.08, 10.5.6.4. PDP type organization must be set to 'IETF allocated
address'.
4.2.3. PDP Info
This is a container for information elements describing a single PDP.
IEI Info Element Type Pres. Format Length
PDP Info IEI M V 1
Length of PDP Info IE length, no ext M V 1
10 PDP context id big endian int, 1-N C TLV 3
11 PDP type 4.2.4 C TLV 4
12 Access point name 04.08, 10.5.6.1 C TLV 3-102
13 Quality of Service 4.2.11 O TLV 1-20
The conditional IE are mandantory unless mentioned otherwise.
4.2.4. PDP Type
The PDP type value consists of 2 octets that are encoded like octet 4-5 of the
End User Address defined in GSM 09.60, 7.9.18.
8 7 6 5 4 3 2 1
+-----------------------------------------------------+
| | PDP type IEI | octet 1
+-----------------------------------------------------+
| Length of PDP type IE contents (2) | octet 2
+-----------------------------------------------------+
| Spare | PDP type org. | octet 3
+-----------------------------------------------------+
| PDP type number | octet 4
+-----------------------------------------------------+
The spare bits are left undefined. While 09.60 defines them as '1 1 1 1', there
are MAP traces where these bits are set to '0 0 0 0'. So the receiver shall
ignore these bits.
Examples:
IPv4: PDP type org: 1 (IETF), PDP type number: 0x21
IPv6: PDP type org: 1 (IETF), PDP type number: 0x57
4.2.5. Auth tuple
This is a container for information elements describing a single authentication
tuple.
IEI Info Element Type Pres. Format Length
Auth. Tuple IEI M V 1
Length of Ath Tuple IE length, no ext M V 1
20 RAND octet string (16) M TLV 18
21 SRES octet string (4) M TLV 6
22 Kc octet string (8) M TLV 10
4.2.6. Cancellation Type
8 7 6 5 4 3 2 1
+-----------------------------------------------------+
| | Cancellation type IEI | octet 1
+-----------------------------------------------------+
| Length of Cancellation Type IE contents (1) | octet 2
+-----------------------------------------------------+
| Cancellation type number | octet 4
+-----------------------------------------------------+
Where the cancellation type number is:
+---------------------------------------------------+
| 8 7 6 5 4 3 2 1 |
| |
| 0 0 0 0 0 0 0 0 - Update Procedure |
| 0 0 0 0 0 0 0 1 - Subscription Withdraw |
+---------------------------------------------------+
4.2.7. IE Identifier (informational)
These are the standard values for the IEI. See the message definitions for the
IEI that shall be used for the encoding.
+---------------------------------------------------------+
| IEI Info Element Type |
| |
| 0x01 IMSI Mobile identity, 04.08: 10.5.1.4 |
| 0x02 Cause GMM cause, 04.08: 10.5.5.14 |
| 0x03 Auth tuple 4.2.5 |
| 0x04 PDP info compl 4.2.8 |
| 0x05 PDP info 4.2.3 |
| 0x06 Cancel type 4.2.6 |
| 0x07 Freeze P-TMSI 4.2.8 |
| 0x08 MSISDN ISDN-AddressString/octet, 4.2.10 |
| 0x09 HLR Number 4.2.12 |
| 0x10 PDP context id big endian int |
| 0x11 PDP type 4.2.4 |
| 0x12 APN 04.08, 10.5.6.1 |
| 0x13 QoS 4.2.11 |
| 0x20 RAND octet string |
| 0x21 SRES octet string |
| 0x22 Kc octet string |
+---------------------------------------------------------+
4.2.8 Empty field
This is used for flags, if and only if this IE is present, the flag is set.
The semantics depend on the IEI and the context.
8 7 6 5 4 3 2 1
+-----------------------------------------------------+
| | IEI | octet 1
+-----------------------------------------------------+
| Length of IE contents (0) | octet 2
+-----------------------------------------------------+
4.2.9. IMSI
The IMSI is encoded like in octet 4-N of the Called Party BCD Number defined in GSM 04.08, 10.5.4.7.
8 7 6 5 4 3 2 1
+-----------------------------------------------------+
| | IMSI IEI | octet 1
+-----------------------------------------------------+
| Length of IMSI IE contents | octet 2
+-----------------------------------------------------+
| Number digit 2 | Number digit 1 | octet 3
+-----------------------------------------------------+
| Number digit 4 | Number digit 3 | octet 4
+-----------------------------------------------------+
: : :
+-----------------------------------------------------+
| see note 1) | octet 2+(N+1)div2
+-----------------------------------------------------+
Note 1) Either '1 1 1 1 | Number digit N' (N odd) or
'Number digit N | Number digit N-1' (N even),
where N is the number of digits.
4.2.10. ISDN-AddressString / MSISDN / Called Party BCD Number
The MSISDN is encoded as an ISDN-AddressString in GSM 09.02 and Called Party
BCD Number in GSM 04.08. It will be stored by the SGSN and then passed as is
to the GGSN during the activation of the primary PDP Context.
8 7 6 5 4 3 2 1
+-----------------------------------------------------+
| | IEI | octet 1
+-----------------------------------------------------+
| Length of IE contents | octet 2
+-----------------------------------------------------+
| ext | Type of num | Numbering plan | octet 2
+-----------------------------------------------------+
| Number digit 2 | Number digit 1 | octet 3
+-----------------------------------------------------+
| Number digit 4 | Number digit 3 | octet 4
+-----------------------------------------------------+
: : :
+-----------------------------------------------------+
4.2.11 Quality of Service Subscribed Service
This encodes the subscribed QoS of a subscriber. It will be used by the
SGSN during the PDP Context activation. If the length of the QoS data
is 3 (three) octets it is assumed that these are octets 3-5 of the TS
3GPP TS 24.008 Quality of Service Octets. If it is more than three then
then it is assumed that the first octet is the Allocation/Retention
Priority and the reset are encoded as octets 3-N of 24.008.
8 7 6 5 4 3 2 1
+-----------------------------------------------------+
| | IEI | octet 1
+-----------------------------------------------------+
| Length of IE contents | octet 2
+-----------------------------------------------------+
: : :
+-----------------------------------------------------+
4.2.12. HLR Number encoded as GSM 09.02 ISDN-AddressString
The HLR Number is encoded as an ISDN-AddressString in GSM 09.02. It
will be stored by the SGSN can be used by the CDR module to keep a
record.
8 7 6 5 4 3 2 1
+-----------------------------------------------------+
| | IEI | octet 1
+-----------------------------------------------------+
| Length of IE contents | octet 2
+-----------------------------------------------------+
| ext | Type of num | Numbering plan | octet 2
+-----------------------------------------------------+
| Number digit 2 | Number digit 1 | octet 3
+-----------------------------------------------------+
| Number digit 4 | Number digit 3 | octet 4
+-----------------------------------------------------+
: : :
+-----------------------------------------------------+