diff --git a/openbsc/doc/sgsn-remote-protocol.txt b/openbsc/doc/sgsn-remote-protocol.txt
new file mode 100644
index 0000000..7ca9094
--- /dev/null
+++ b/openbsc/doc/sgsn-remote-protocol.txt
@@ -0,0 +1,385 @@
+
+               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. 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
+  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
+
+3.2.10. Purge MS Error
+
+Network peer -> SGSN
+
+TODO
+
+3.2.11. Purge MS Result
+
+Network peer -> SGSN
+
+TODO
+
+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
+
+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                             |
+  | 0x10   PDP context id big endian int                    |
+  | 0x11   PDP type       4.2.4                             |
+  | 0x12   APN            04.08, 10.5.6.1                   |
+  | 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.