blob: 7f304a3caae0d8695f809345f5a7bdf0c81c3c9a [file] [log] [blame]
Harald Welte381a1aa2017-10-16 18:31:20 +02001/*! \defgroup gsup Generic Subscriber Update Protocol
2 * @{
3 *
4 * The Generic Subscriber Update Protocol (GSUP) is an Osmocom-specific
5 * non-standard protocol replacing MAP as the protocol between
6 * MSC/VLR/SGSN and HLR in a 3GPP cellular communications network.
7 *
8 * It was designed around the same transactions and architecture as the
9 * MAP messages/operations, but without the complexity of TCAP and MAP,
10 * and without the need for ASN.1 encoding.
11 *
12 * The purpose is to keep protocol complexity out of OsmoSGSN and
13 * OsmoMSC, while providing a clean path to an external GSUP to MAP
14 * translator.
15 *
16 * \file gsup.h
17 * Osmocom Generic Subscriber Update Protocol message encoder/decoder. */
Neels Hofmeyr17518fe2017-06-20 04:35:06 +020018/*
Harald Weltee08da972017-11-13 01:00:26 +090019 * (C) 2014 by sysmocom - s.f.m.c. GmbH, Author: Jacob Erlbeck
Harald Welte3b6fb082016-04-25 18:46:22 +020020 * (C) 2016 by Harald Welte <laforge@gnumonks.org>
21 * All Rights Reserved
22 *
Harald Weltee08da972017-11-13 01:00:26 +090023 * SPDX-License-Identifier: GPL-2.0+
24 *
Harald Welte3b6fb082016-04-25 18:46:22 +020025 * This program is free software; you can redistribute it and/or modify
26 * it under the terms of the GNU General Public License as published by
27 * the Free Software Foundation; either version 2 of the License, or
28 * (at your option) any later version.
29 *
30 * This program is distributed in the hope that it will be useful,
31 * but WITHOUT ANY WARRANTY; without even the implied warranty of
32 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
33 * GNU General Public License for more details.
34 *
35 * You should have received a copy of the GNU General Public License
36 * along with this program. If not, see <http://www.gnu.org/licenses/>.
37 *
38 */
39#pragma once
40
41#include <stdint.h>
42#include <osmocom/core/msgb.h>
Vadim Yanitskiyc2628312018-09-25 23:03:13 +070043#include <osmocom/gsm/gsup_sms.h>
Harald Welte3b6fb082016-04-25 18:46:22 +020044#include <osmocom/gsm/protocol/gsm_23_003.h>
45#include <osmocom/gsm/protocol/gsm_04_08_gprs.h>
46#include <osmocom/crypt/auth.h>
47
Neels Hofmeyrb970e102017-07-21 15:55:28 +020048#define OSMO_GSUP_PORT 4222
49
Harald Welte3b6fb082016-04-25 18:46:22 +020050/*! Maximum nubmer of PDP inside \ref osmo_gsup_message */
51#define OSMO_GSUP_MAX_NUM_PDP_INFO 10 /* GSM 09.02 limits this to 50 */
52/*! Maximum number of auth info inside \ref osmo_gsup_message */
53#define OSMO_GSUP_MAX_NUM_AUTH_INFO 5
54/*! Maximum number of octets encoding MSISDN in BCD format */
55#define OSMO_GSUP_MAX_MSISDN_LEN 9
Stefan Sperlingdda1d452018-05-03 11:50:32 +020056#define OSMO_GSUP_MAX_CALLED_PARTY_BCD_LEN 43 /* TS 24.008 10.5.4.7 */
Harald Welte3b6fb082016-04-25 18:46:22 +020057
58#define OSMO_GSUP_PDP_TYPE_SIZE 2
59
60/*! Information Element Identifiers for GSUP IEs */
61enum osmo_gsup_iei {
62 OSMO_GSUP_IMSI_IE = 0x01,
63 OSMO_GSUP_CAUSE_IE = 0x02,
64 OSMO_GSUP_AUTH_TUPLE_IE = 0x03,
65 OSMO_GSUP_PDP_INFO_COMPL_IE = 0x04,
66 OSMO_GSUP_PDP_INFO_IE = 0x05,
67 OSMO_GSUP_CANCEL_TYPE_IE = 0x06,
68 OSMO_GSUP_FREEZE_PTMSI_IE = 0x07,
69 OSMO_GSUP_MSISDN_IE = 0x08,
70 OSMO_GSUP_HLR_NUMBER_IE = 0x09,
Neels Hofmeyr9838c902019-04-01 22:24:33 +020071 OSMO_GSUP_MESSAGE_CLASS_IE = 0x0a,
Harald Welte3b6fb082016-04-25 18:46:22 +020072 OSMO_GSUP_PDP_CONTEXT_ID_IE = 0x10,
73 OSMO_GSUP_PDP_TYPE_IE = 0x11,
74 OSMO_GSUP_ACCESS_POINT_NAME_IE = 0x12,
75 OSMO_GSUP_PDP_QOS_IE = 0x13,
Holger Hans Peter Freythereb55c0d2017-07-07 16:53:30 +020076 OSMO_GSUP_CHARG_CHAR_IE = 0x14,
Harald Welte3b6fb082016-04-25 18:46:22 +020077 OSMO_GSUP_RAND_IE = 0x20,
78 OSMO_GSUP_SRES_IE = 0x21,
79 OSMO_GSUP_KC_IE = 0x22,
80 /* 3G support */
81 OSMO_GSUP_IK_IE = 0x23,
82 OSMO_GSUP_CK_IE = 0x24,
83 OSMO_GSUP_AUTN_IE = 0x25,
84 OSMO_GSUP_AUTS_IE = 0x26,
85 OSMO_GSUP_RES_IE = 0x27,
Harald Welte48dc1a52016-05-05 18:46:42 +020086 OSMO_GSUP_CN_DOMAIN_IE = 0x28,
Vadim Yanitskiy72696042018-04-07 02:34:55 +070087
88 OSMO_GSUP_SESSION_ID_IE = 0x30,
89 OSMO_GSUP_SESSION_STATE_IE = 0x31,
Vadim Yanitskiy36c7b332018-03-31 05:23:09 +070090
91 /*! Supplementary Services payload */
92 OSMO_GSUP_SS_INFO_IE = 0x35,
Vadim Yanitskiyc2628312018-09-25 23:03:13 +070093
94 /* SM related IEs (see 3GPP TS 29.002, section 7.6.8) */
95 OSMO_GSUP_SM_RP_MR_IE = 0x40,
96 OSMO_GSUP_SM_RP_DA_IE = 0x41,
97 OSMO_GSUP_SM_RP_OA_IE = 0x42,
98 OSMO_GSUP_SM_RP_UI_IE = 0x43,
99 OSMO_GSUP_SM_RP_CAUSE_IE = 0x44,
100 OSMO_GSUP_SM_RP_MMS_IE = 0x45,
Vadim Yanitskiyf9ee8da2018-11-13 02:06:15 +0700101 OSMO_GSUP_SM_ALERT_RSN_IE = 0x46,
Oliver Smith19742402018-12-21 10:18:28 +0100102
Oliver Smith10db2812018-12-14 16:14:34 +0100103 OSMO_GSUP_IMEI_IE = 0x50,
104 OSMO_GSUP_IMEI_RESULT_IE = 0x51,
105
Oliver Smith19742402018-12-21 10:18:28 +0100106 _OSMO_GSUP_IEI_END_MARKER
Harald Welte3b6fb082016-04-25 18:46:22 +0200107};
108
Oliver Smithd6ff9c82019-02-01 15:21:25 +0100109/*! GSUP message type
110 * Make sure that new messages follow this scheme:
111 * .----------------------------.
112 * | Ending Bits | Category |
113 * |----------------------------|
114 * | 00 | Request |
115 * | 01 | Error |
116 * | 10 | Result |
117 * | 11 | Other |
118 * '----------------------------'
119 * Request, Error and Result messages must only differ in these last two bits.
120 */
Harald Welte3b6fb082016-04-25 18:46:22 +0200121enum osmo_gsup_message_type {
122 OSMO_GSUP_MSGT_UPDATE_LOCATION_REQUEST = 0b00000100,
123 OSMO_GSUP_MSGT_UPDATE_LOCATION_ERROR = 0b00000101,
124 OSMO_GSUP_MSGT_UPDATE_LOCATION_RESULT = 0b00000110,
125
126 OSMO_GSUP_MSGT_SEND_AUTH_INFO_REQUEST = 0b00001000,
127 OSMO_GSUP_MSGT_SEND_AUTH_INFO_ERROR = 0b00001001,
128 OSMO_GSUP_MSGT_SEND_AUTH_INFO_RESULT = 0b00001010,
129
Harald Weltede960cb2016-06-16 22:57:09 +0200130 OSMO_GSUP_MSGT_AUTH_FAIL_REPORT = 0b00001011,
131
Harald Welte3b6fb082016-04-25 18:46:22 +0200132 OSMO_GSUP_MSGT_PURGE_MS_REQUEST = 0b00001100,
133 OSMO_GSUP_MSGT_PURGE_MS_ERROR = 0b00001101,
134 OSMO_GSUP_MSGT_PURGE_MS_RESULT = 0b00001110,
135
136 OSMO_GSUP_MSGT_INSERT_DATA_REQUEST = 0b00010000,
137 OSMO_GSUP_MSGT_INSERT_DATA_ERROR = 0b00010001,
138 OSMO_GSUP_MSGT_INSERT_DATA_RESULT = 0b00010010,
139
140 OSMO_GSUP_MSGT_DELETE_DATA_REQUEST = 0b00010100,
141 OSMO_GSUP_MSGT_DELETE_DATA_ERROR = 0b00010101,
142 OSMO_GSUP_MSGT_DELETE_DATA_RESULT = 0b00010110,
143
144 OSMO_GSUP_MSGT_LOCATION_CANCEL_REQUEST = 0b00011100,
145 OSMO_GSUP_MSGT_LOCATION_CANCEL_ERROR = 0b00011101,
146 OSMO_GSUP_MSGT_LOCATION_CANCEL_RESULT = 0b00011110,
Vadim Yanitskiy36c7b332018-03-31 05:23:09 +0700147
148 OSMO_GSUP_MSGT_PROC_SS_REQUEST = 0b00100000,
149 OSMO_GSUP_MSGT_PROC_SS_ERROR = 0b00100001,
150 OSMO_GSUP_MSGT_PROC_SS_RESULT = 0b00100010,
Vadim Yanitskiyc2628312018-09-25 23:03:13 +0700151
152 OSMO_GSUP_MSGT_MO_FORWARD_SM_REQUEST = 0b00100100,
153 OSMO_GSUP_MSGT_MO_FORWARD_SM_ERROR = 0b00100101,
154 OSMO_GSUP_MSGT_MO_FORWARD_SM_RESULT = 0b00100110,
155
156 OSMO_GSUP_MSGT_MT_FORWARD_SM_REQUEST = 0b00101000,
157 OSMO_GSUP_MSGT_MT_FORWARD_SM_ERROR = 0b00101001,
158 OSMO_GSUP_MSGT_MT_FORWARD_SM_RESULT = 0b00101010,
Vadim Yanitskiyf9ee8da2018-11-13 02:06:15 +0700159
160 OSMO_GSUP_MSGT_READY_FOR_SM_REQUEST = 0b00101100,
161 OSMO_GSUP_MSGT_READY_FOR_SM_ERROR = 0b00101101,
162 OSMO_GSUP_MSGT_READY_FOR_SM_RESULT = 0b00101110,
Oliver Smith10db2812018-12-14 16:14:34 +0100163
164 OSMO_GSUP_MSGT_CHECK_IMEI_REQUEST = 0b00110000,
165 OSMO_GSUP_MSGT_CHECK_IMEI_ERROR = 0b00110001,
166 OSMO_GSUP_MSGT_CHECK_IMEI_RESULT = 0b00110010,
Harald Welte3b6fb082016-04-25 18:46:22 +0200167};
168
169#define OSMO_GSUP_IS_MSGT_REQUEST(msgt) (((msgt) & 0b00000011) == 0b00)
170#define OSMO_GSUP_IS_MSGT_ERROR(msgt) (((msgt) & 0b00000011) == 0b01)
171#define OSMO_GSUP_TO_MSGT_ERROR(msgt) (((msgt) & 0b11111100) | 0b01)
172
Neels Hofmeyr10f5fb42017-02-09 02:09:09 +0100173extern const struct value_string osmo_gsup_message_type_names[];
174static inline const char *
175osmo_gsup_message_type_name(enum osmo_gsup_message_type val)
176{ return get_value_string(osmo_gsup_message_type_names, val); }
177
Harald Welte3b6fb082016-04-25 18:46:22 +0200178enum osmo_gsup_cancel_type {
179 OSMO_GSUP_CANCEL_TYPE_UPDATE = 1, /* on wire: 0 */
180 OSMO_GSUP_CANCEL_TYPE_WITHDRAW = 2, /* on wire: 1 */
181};
182
Harald Welte48dc1a52016-05-05 18:46:42 +0200183enum osmo_gsup_cn_domain {
184 OSMO_GSUP_CN_DOMAIN_PS = 1,
185 OSMO_GSUP_CN_DOMAIN_CS = 2,
186};
187
Oliver Smith10db2812018-12-14 16:14:34 +0100188enum osmo_gsup_imei_result {
Oliver Smithd621a1e2019-01-08 16:22:30 +0100189 OSMO_GSUP_IMEI_RESULT_ACK = 1, /* on wire: 0 */
190 OSMO_GSUP_IMEI_RESULT_NACK = 2, /* on wire: 1 */
Oliver Smith10db2812018-12-14 16:14:34 +0100191};
192
Vadim Yanitskiy72696042018-04-07 02:34:55 +0700193/*! TCAP-like session state */
194enum osmo_gsup_session_state {
195 /*! Undefined session state */
196 OSMO_GSUP_SESSION_STATE_NONE = 0x00,
197 /*! Initiation of a new session */
198 OSMO_GSUP_SESSION_STATE_BEGIN = 0x01,
199 /*! Communication of an existing session */
200 OSMO_GSUP_SESSION_STATE_CONTINUE = 0x02,
201 /*! Indication of the session end */
202 OSMO_GSUP_SESSION_STATE_END = 0x03,
203};
204
Harald Welte6a6a6092018-06-16 11:10:12 +0200205extern const struct value_string osmo_gsup_session_state_names[];
206static inline const char *
207osmo_gsup_session_state_name(enum osmo_gsup_session_state val)
208{ return get_value_string(osmo_gsup_session_state_names, val); }
209
Harald Welte3b6fb082016-04-25 18:46:22 +0200210/*! parsed/decoded PDP context information */
211struct osmo_gsup_pdp_info {
212 unsigned int context_id;
213 int have_info;
214 /*! Type of PDP context */
215 uint16_t pdp_type;
216 /*! APN information, still in encoded form. Can be NULL if no
217 * APN information included */
218 const uint8_t *apn_enc;
219 /*! length (in octets) of apn_enc */
220 size_t apn_enc_len;
221 /*! QoS information, still in encoded form. Can be NULL if no
222 * QoS information included */
223 const uint8_t *qos_enc;
224 /*! length (in octets) of qos_enc */
225 size_t qos_enc_len;
Holger Hans Peter Freythereb55c0d2017-07-07 16:53:30 +0200226 /*! PDP Charging Characteristics, still in encoded form. Can be NULL if no
227 * PDP Charging Characteristics */
228 const uint8_t *pdp_charg_enc;
229 /*! length (in octets) of pdp_charg_enc */
230 size_t pdp_charg_enc_len;
Harald Welte3b6fb082016-04-25 18:46:22 +0200231};
232
Neels Hofmeyr9838c902019-04-01 22:24:33 +0200233enum osmo_gsup_message_class {
234 OSMO_GSUP_MESSAGE_CLASS_UNSET = 0,
235 OSMO_GSUP_MESSAGE_CLASS_SUBSCRIBER_MANAGEMENT = 1,
236 OSMO_GSUP_MESSAGE_CLASS_SMS = 2,
237 OSMO_GSUP_MESSAGE_CLASS_USSD = 3,
238 OSMO_GSUP_MESSAGE_CLASS_INTER_MSC = 4,
239 /* Keep this as last entry with a value of max(enum osmo_gsup_message_class) + 1.
240 * This value shall serve as the size for an array to aid de-muxing all known GSUP classes. */
241 OSMO_GSUP_MESSAGE_CLASS_ARRAYSIZE
242};
243
244extern const struct value_string osmo_gsup_message_class_names[];
245static inline const char *osmo_gsup_message_class_name(enum osmo_gsup_message_class val)
246{ return get_value_string(osmo_gsup_message_class_names, val); }
247
Harald Welte3b6fb082016-04-25 18:46:22 +0200248/*! parsed/decoded GSUP protocol message */
249struct osmo_gsup_message {
250 enum osmo_gsup_message_type message_type;
Neels Hofmeyr0ee798a2019-04-10 19:13:19 +0200251 char imsi[OSMO_IMSI_BUF_SIZE];
Harald Welte3b6fb082016-04-25 18:46:22 +0200252 enum gsm48_gmm_cause cause;
253 enum osmo_gsup_cancel_type cancel_type;
254 int pdp_info_compl;
255 int freeze_ptmsi;
256 struct osmo_auth_vector auth_vectors[OSMO_GSUP_MAX_NUM_AUTH_INFO];
257 size_t num_auth_vectors;
258 struct osmo_gsup_pdp_info pdp_infos[OSMO_GSUP_MAX_NUM_PDP_INFO];
259 size_t num_pdp_infos;
260 const uint8_t *msisdn_enc;
261 size_t msisdn_enc_len;
262 const uint8_t *hlr_enc;
263 size_t hlr_enc_len;
264 const uint8_t *auts;
Harald Welte766da862016-05-06 11:18:15 +0200265 const uint8_t *rand;
Harald Welte48dc1a52016-05-05 18:46:42 +0200266 enum osmo_gsup_cn_domain cn_domain;
Holger Hans Peter Freythereb55c0d2017-07-07 16:53:30 +0200267 const uint8_t *pdp_charg_enc;
268 size_t pdp_charg_enc_len;
Vadim Yanitskiy72696042018-04-07 02:34:55 +0700269
270 /*! Session state \ref osmo_gsup_session_state */
271 enum osmo_gsup_session_state session_state;
272 /*! Unique session identifier and origination flag.
Vadim Yanitskiy5a7b4652018-11-06 18:24:49 +0700273 * Encoded only when \ref session_state != 0x00 */
Vadim Yanitskiy72696042018-04-07 02:34:55 +0700274 uint32_t session_id;
Vadim Yanitskiy36c7b332018-03-31 05:23:09 +0700275
276 /*! ASN.1 encoded MAP payload for Supplementary Services */
277 uint8_t *ss_info;
278 size_t ss_info_len;
Vadim Yanitskiyc2628312018-09-25 23:03:13 +0700279
280 /*! SM-RP-MR (see 3GPP TS 29.002, 7.6.1.1), Message Reference.
281 * Please note that there is no SM-RP-MR in TCAP/MAP! SM-RP-MR
282 * is usually mapped to TCAP's InvokeID, but we don't need it. */
283 const uint8_t *sm_rp_mr;
284 /*! SM-RP-DA (see 3GPP TS 29.002, 7.6.8.1), Destination Address */
285 enum osmo_gsup_sms_sm_rp_oda_t sm_rp_da_type;
286 size_t sm_rp_da_len;
287 const uint8_t *sm_rp_da;
288 /*! SM-RP-OA (see 3GPP TS 29.002, 7.6.8.2), Originating Address */
289 enum osmo_gsup_sms_sm_rp_oda_t sm_rp_oa_type;
290 size_t sm_rp_oa_len;
291 const uint8_t *sm_rp_oa;
292 /*! SM-RP-UI (see 3GPP TS 29.002, 7.6.8.4), SMS TPDU */
293 const uint8_t *sm_rp_ui;
294 size_t sm_rp_ui_len;
295 /*! SM-RP-Cause value (1 oct.) as per GSM TS 04.11, section 8.2.5.4 */
296 const uint8_t *sm_rp_cause;
297 /*! SM-RP-MMS (More Messages to Send), section 7.6.8.7 */
298 const uint8_t *sm_rp_mms;
Vadim Yanitskiyf9ee8da2018-11-13 02:06:15 +0700299 /*! Alert reason (see 3GPP TS 29.002, 7.6.8.8) */
300 enum osmo_gsup_sms_sm_alert_rsn_t sm_alert_rsn;
Oliver Smith10db2812018-12-14 16:14:34 +0100301
302 const uint8_t *imei_enc;
303 size_t imei_enc_len;
304 enum osmo_gsup_imei_result imei_result;
Neels Hofmeyr9838c902019-04-01 22:24:33 +0200305
306 /*! Indicate the message class to trivially dispatch incoming GSUP messages to the right code paths.
307 * Inter-MSC messages are *required* to set a class = OSMO_GSUP_MESSAGE_CLASS_INTER_MSC. For older message classes, this may
308 * be omitted (for backwards compatibility only -- if in doubt, include it). */
309 enum osmo_gsup_message_class message_class;
Harald Welte3b6fb082016-04-25 18:46:22 +0200310};
311
312int osmo_gsup_decode(const uint8_t *data, size_t data_len,
313 struct osmo_gsup_message *gsup_msg);
Max80f4c4e2018-01-24 12:33:05 +0100314int osmo_gsup_encode(struct msgb *msg, const struct osmo_gsup_message *gsup_msg);
Oliver Smithd6ff9c82019-02-01 15:21:25 +0100315int osmo_gsup_get_err_msg_type(enum osmo_gsup_message_type type_in)
316 OSMO_DEPRECATED("Use OSMO_GSUP_TO_MSGT_ERROR() instead");
Harald Welte381a1aa2017-10-16 18:31:20 +0200317
318/*! @} */