libosmosim  1.9.0.17-a59e8.202310212026
Osmocom SIM library
sim.h
Go to the documentation of this file.
1 
5 #pragma once
6 
7 #include <osmocom/core/msgb.h>
8 #include <osmocom/core/linuxlist.h>
9 
10 #define APDU_HDR_LEN 5
11 #define MAX_AID_LEN 16 /* Table 13.2 of TS 102 221 */
12 
13 
18 #define OSIM_MAX_ATR_LEN 33
19 
32 };
33 
44  uint8_t cla;
45  uint8_t ins;
46  uint8_t p1;
47  uint8_t p2;
48  uint8_t p3;
49 } __attribute__ ((packed));
50 
51 #define msgb_apdu_dr(__x)
52 
58 struct osim_msgb_cb {
60  uint16_t lc;
61  uint16_t le;
62  uint16_t sw;
63 } __attribute__((__may_alias__));
64 #define OSIM_MSGB_CB(__msgb) ((struct osim_msgb_cb *)&((__msgb)->cb[0]))
65 
66 #define msgb_apdu_case(__x) OSIM_MSGB_CB(__x)->apduc
67 #define msgb_apdu_lc(__x) OSIM_MSGB_CB(__x)->lc
68 #define msgb_apdu_le(__x) OSIM_MSGB_CB(__x)->le
69 #define msgb_apdu_sw(__x) OSIM_MSGB_CB(__x)->sw
70 
71 #define msgb_apdu_h(__x) ((struct osim_apdu_cmd_hdr *)(__x)->l2h)
72 
73 #define msgb_apdu_dc(__x) ((__x)->l2h + sizeof(struct osim_apdu_cmd_hdr))
74 #define msgb_apdu_de(__x) ((__x)->l2h + sizeof(struct osim_apdu_cmd_hdr) + msgb_apdu_lc(__x))
75 
76 int osim_init(void *ctx);
77 
78 /* FILES */
79 
80 struct osim_file;
81 struct osim_file_desc;
82 struct osim_decoded_data;
83 
85 struct osim_file_ops {
87  int (*parse)(struct osim_decoded_data *dd,
88  const struct osim_file_desc *desc,
89  int len, uint8_t *data);
91  struct msgb * (*encode)(const struct osim_file_desc *desc,
92  const struct osim_decoded_data *decoded);
93 };
94 
105 };
106 
111 };
112 
115  struct llist_head list;
116 
117  enum osim_element_type type;
118  enum osim_element_repr representation;
119  const char *name;
120 
121  unsigned int length;
122  union {
123  uint8_t u8;
124  uint16_t u16;
125  uint32_t u32;
126  uint8_t *buf;
128  struct llist_head siblings;
129  } u;
130 };
131 
135  const struct osim_file *file;
137  struct llist_head decoded_elements;
138 };
139 
140 
148 };
149 
155 };
156 
157 #define F_OPTIONAL 0x0001
158 
159 #define SFI_NONE 0xFF
160 
162  struct llist_head list;
163  struct llist_head child_list;
169  uint16_t fid;
170  uint8_t sfid;
171  const uint8_t *df_name;
172  uint8_t df_name_len;
173 
174  const char *short_name;
175  const char *long_name;
176  unsigned int flags;
177 
178  struct osim_file_ops ops;
180  struct {
181  size_t min;
184  size_t rec;
185  } size;
186 };
187 
189 struct osim_file {
191  const struct osim_file_desc *desc;
192 
194  struct msgb *encoded_data;
197 };
198 
200 #define EF(pfid, sfi, pns, pflags, pnl, ptype, smin, srec, pdec, penc) \
201  { \
202  .fid = pfid, \
203  .sfid = sfi, \
204  .type = TYPE_EF, \
205  .ef_type = ptype, \
206  .short_name = pns, \
207  .long_name = pnl, \
208  .flags = pflags, \
209  .ops = { .encode = penc, .parse = pdec }, \
210  .size = { .min = smin, .rec = srec}, \
211  }
212 
213 
215 #define EF_TRANSP(fid, sfi, ns, flags, smin, srec, nl, dec, enc) \
216  EF(fid, sfi, ns, flags, nl, EF_TYPE_TRANSP, \
217  smin, srec, dec, enc)
218 
219 #define EF_TRANSP_N(fid, sfi, ns, flags, smin, srec, nl) \
220  EF_TRANSP(fid, sfi, ns, flags, smin, srec, \
221  nl, &default_decode, NULL)
222 
224 #define EF_CYCLIC(fid, sfi, ns, flags, smin, srec, nl, dec, enc) \
225  EF(fid, sfi, ns, flags, nl, EF_TYPE_RECORD_CYCLIC, \
226  smin, srec, dec, enc)
227 
228 #define EF_CYCLIC_N(fid, sfi, ns, flags, smin, srec, nl) \
229  EF_CYCLIC(fid, sfi, ns, flags, smin, srec, nl, \
230  &default_decode, NULL)
231 
233 #define EF_LIN_FIX(fid, sfi, ns, flags, smin, srec, nl, dec, enc) \
234  EF(fid, sfi, ns, flags, nl, EF_TYPE_RECORD_FIXED, \
235  smin, srec, dec, enc)
236 
237 #define EF_LIN_FIX_N(fid, sfi, ns, flags, smin, srec, nl) \
238  EF_LIN_FIX(fid, sfi, ns, flags, smin, srec, nl, \
239  &default_decode, NULL)
240 
242 #define EF_KEY(fid, sfi, ns, flags, smin, srec, nl, dec, enc) \
243  EF(fid, sfi, ns, flags, nl, EF_TYPE_KEY, \
244  smin, srec, dec, enc)
245 
246 #define EF_KEY_N(fid, sfi, ns, flags, smin, srec, nl) \
247  EF_KEY(fid, sfi, ns, flags, smin, srec, nl, \
248  &default_decode, NULL)
249 
250 
251 struct osim_file_desc *
252 osim_file_desc_find_name(struct osim_file_desc *parent, const char *name);
253 
254 struct osim_file_desc *
255 osim_file_desc_find_aid(struct osim_file_desc *parent, const uint8_t *aid, uint8_t aid_len);
256 
257 struct osim_file_desc *
259 
260 struct osim_file_desc *
262 
263 /* STATUS WORDS */
264 
268 };
269 
276 };
277 
279 struct osim_card_sw {
281  uint16_t code;
283  uint16_t mask;
284  enum osim_card_sw_type type;
285  enum osim_card_sw_class class;
286  union {
288  const char *str;
289  } u;
290 };
291 
292 #define OSIM_CARD_SW_LAST { \
293  .code = 0, .mask = 0, .type = SW_TYPE_NONE, \
294  .class = SW_CLS_NONE, .u.str = NULL \
295 }
296 
300  struct llist_head list;
302  const char *name;
304  uint8_t aid[MAX_AID_LEN];
305  uint8_t aid_len;
309  const struct osim_card_sw *sw;
310 };
311 
312 const struct osim_card_app_profile *
314 
315 const struct osim_card_app_profile *
316 osim_app_profile_find_by_aid(const uint8_t *aid, uint8_t aid_len);
317 
318 const struct osim_card_sw *osim_app_profile_find_sw(const struct osim_card_app_profile *ap, uint16_t sw_in);
319 
322  const char *name;
326  const struct osim_card_sw **sws;
327 };
328 
329 const struct osim_card_sw *osim_cprof_find_sw(const struct osim_card_profile *cp, uint16_t sw_in);
330 
331 struct osim_chan_hdl;
332 enum osim_card_sw_class osim_sw_class(const struct osim_chan_hdl *ch, uint16_t sw_in);
333 char *osim_print_sw_buf(char *buf, size_t buf_len, const struct osim_chan_hdl *ch, uint16_t sw_in);
334 char *osim_print_sw(const struct osim_chan_hdl *ch, uint16_t sw_in);
335 char *osim_print_sw_c(const void *ctx, const struct osim_chan_hdl *ch, uint16_t sw_in);
336 
337 extern const struct tlv_definition ts102221_fcp_tlv_def;
338 extern const struct value_string ts102221_fcp_vals[14];
339 
340 /* 11.1.1.3 */
355 };
356 
357 struct msgb *osim_new_apdumsg(uint8_t cla, uint8_t ins, uint8_t p1,
358  uint8_t p2, uint16_t lc, uint16_t le);
359 
360 /* CARD READERS */
361 
365 };
366 
371 };
372 
374  const char *name;
375  struct osim_reader_hdl *(*reader_open)(int idx, const char *name, void *ctx);
376  struct osim_card_hdl *(*card_open)(struct osim_reader_hdl *rh, enum osim_proto proto);
377  int (*card_reset)(struct osim_card_hdl *card, bool cold_reset);
378  int (*card_close)(struct osim_card_hdl *card);
379  int (*transceive)(struct osim_reader_hdl *rh, struct msgb *msg);
380 };
381 
384  struct llist_head list;
385  const struct osim_reader_ops *ops;
386  uint32_t proto_supported;
387  void *priv;
390 };
391 
395  struct llist_head list;
397  uint8_t aid[MAX_AID_LEN];
398  uint8_t aid_len;
400  char *label;
403 };
404 
407  struct llist_head list;
413  enum osim_proto proto;
414 
416  struct llist_head channels;
417 
419  struct llist_head apps;
420 
422  uint8_t atr[OSIM_MAX_ATR_LEN];
423  unsigned int atr_len;
424 };
425 
428  struct llist_head list;
432  const struct osim_file_desc *cwd;
435 };
436 
437 int osim_card_hdl_add_app(struct osim_card_hdl *ch, const uint8_t *aid, uint8_t aid_len,
438  const char *label);
439 
440 /* reader.c */
441 int osim_transceive_apdu(struct osim_chan_hdl *st, struct msgb *amsg);
442 struct osim_reader_hdl *osim_reader_open(enum osim_reader_driver drv, int idx,
443  const char *name, void *ctx);
445 int osim_card_reset(struct osim_card_hdl *card, bool cold_reset);
446 int osim_card_close(struct osim_card_hdl *card);
const struct osim_card_sw * osim_app_profile_find_sw(const struct osim_card_app_profile *ap, uint16_t sw_in)
Find application-specific status word within given card application profile.
Definition: core.c:431
const struct tlv_definition ts102221_fcp_tlv_def
Definition: card_fs_uicc.c:209
const struct osim_file * file
file to which we belong
Definition: sim.h:135
ts102221_fcp_tag
Definition: sim.h:341
char * osim_print_sw_c(const void *ctx, const struct osim_chan_hdl *ch, uint16_t sw_in)
Definition: core.c:407
struct osim_file_desc * osim_file_desc_find_fid(struct osim_file_desc *parent, uint16_t fid)
Definition: core.c:203
uint8_t aid_len
Definition: sim.h:305
Definition: sim.h:275
command header, no command data field, no response data field
Definition: sim.h:25
const struct osim_file_desc * desc
Descriptor for the file.
Definition: sim.h:191
Decoded data for a single file, consisting of all decoded elements.
Definition: sim.h:133
Definition: sim.h:351
Definition: sim.h:364
osim_reader_driver
Definition: sim.h:367
Internal Entry File.
Definition: sim.h:146
const struct osim_card_sw * sw
Status words defined by application.
Definition: sim.h:309
unsigned integer
Definition: sim.h:99
struct osim_card_hdl * osim_card_open(struct osim_reader_hdl *rh, enum osim_proto proto)
Definition: reader.c:261
descriptor for a given application present on a card
Definition: sim.h:393
uint8_t p1
Parameter 1 byte.
Definition: sim.h:46
const struct osim_card_app_profile * prof
application profile (if any known)
Definition: sim.h:402
const struct osim_reader_ops * ops
Definition: sim.h:385
Definition: sim.h:273
unsigned int flags
Definition: sim.h:176
Definition: sim.h:347
const struct osim_card_app_profile * osim_app_profile_find_by_name(const char *name)
Find any registered application profile based on its name (e.g.
Definition: core.c:245
void * priv
Definition: sim.h:387
const char * name
Definition: sim.h:374
Key file as used in TETRA.
Definition: sim.h:154
Definition: sim.h:274
unsigned int length
Definition: sim.h:121
int osim_card_reset(struct osim_card_hdl *card, bool cold_reset)
Definition: reader.c:277
uint8_t aid[MAX_AID_LEN]
AID of the application.
Definition: sim.h:397
uint16_t lc
number of bytes in the command data field Nc, which will encoded in 0, 1 or 3 bytes into Lc...
Definition: sim.h:33
uint16_t fid
File Identifier.
Definition: sim.h:169
command header, no command data field, response data field (extended)
Definition: sim.h:27
BCD encoded digits.
Definition: sim.h:102
uint16_t code
status word code (2 bytes)
Definition: sim.h:281
Definition: sim.h:426
Definition: sim.h:405
Definition: sim.h:350
osim_apdu_case
command-response pairs cases
Definition: sim.h:24
Dedicated File.
Definition: sim.h:143
uint16_t mask
status word mask (2 bytes), to match range/prefix of SW
Definition: sim.h:283
Definition: sim.h:352
osim_card_sw_class
Definition: sim.h:270
Definition: sim.h:108
Master File.
Definition: sim.h:147
struct osim_card_hdl * card
card to which this channel belongs
Definition: sim.h:430
int osim_transceive_apdu(struct osim_chan_hdl *st, struct msgb *amsg)
Definition: reader.c:224
uint8_t cla
CLASS byte.
Definition: sim.h:44
a boolean flag
Definition: sim.h:97
int osim_card_hdl_add_app(struct osim_card_hdl *ch, const uint8_t *aid, uint8_t aid_len, const char *label)
Add an application to a given card.
Definition: core.c:287
uint16_t sw
status word, composed of SW1 and SW2 bytes
Definition: sim.h:62
unsigned integer
Definition: sim.h:98
uint8_t ins
INSTRUCTION byte.
Definition: sim.h:45
command header, command data field (extended), response data field (extended)
Definition: sim.h:31
Definition: sim.h:343
size_t rec
Recommended size.
Definition: sim.h:184
int osim_init(void *ctx)
Definition: core.c:473
struct osim_file_desc * osim_file_desc_find_sfid(struct osim_file_desc *parent, uint8_t sfid)
Definition: core.c:215
Definition: sim.h:354
const char * name
Definition: sim.h:119
uint8_t aid[MAX_AID_LEN]
AID of this application, as used in EF.DIR.
Definition: sim.h:304
struct osim_file_desc * mf
Descriptor for the MF (root directory.
Definition: sim.h:324
command header, command data field (short), response data field (short)
Definition: sim.h:30
Definition: sim.h:353
Definition: sim.h:271
Definition: sim.h:382
A card application (e.g.
Definition: sim.h:298
A single decoded element inside a file.
Definition: sim.h:114
enum osim_card_sw_class osim_sw_class(const struct osim_chan_hdl *ch, uint16_t sw_in)
Definition: core.c:442
uint8_t * buf
Definition: sim.h:126
Definition: sim.h:370
uint16_t le
maximum number of bytes expected in the response data field, which will encoded in 0...
Definition: sim.h:61
Cyclic Record EF.
Definition: sim.h:153
enum osim_ef_type ef_type
Type of the EF, if type == TYPE_EF.
Definition: sim.h:167
Definition: sim.h:349
char * label
application label from EF_DIR
Definition: sim.h:400
osim_card_sw_type
Definition: sim.h:265
osim_ef_type
Definition: sim.h:150
Application Dedicated File.
Definition: sim.h:144
struct osim_reader_hdl * osim_reader_open(enum osim_reader_driver drv, int idx, const char *name, void *ctx)
Definition: reader.c:234
uint16_t le
maximum number of bytes expected in the response data field, which will encoded in 0...
Definition: sim.h:34
uint8_t aid_len
Definition: sim.h:398
Operations for a given File.
Definition: sim.h:85
group container, has siblings
Definition: sim.h:104
uint8_t sfid
Short File IDentifier.
Definition: sim.h:170
const struct osim_card_sw ** sws
Array of pointers to status words.
Definition: sim.h:326
osim_proto
Definition: sim.h:362
unsigned integer
Definition: sim.h:100
const char * str
Human-readable meaning of SW.
Definition: sim.h:288
command header, command data field (extended), no response data field
Definition: sim.h:29
#define OSIM_MAX_ATR_LEN
Maximum Answer-To-Reset (ATR) size in bytes.
Definition: sim.h:18
const char * long_name
Long / description.
Definition: sim.h:175
Definition: sim.h:342
uint8_t df_name_len
Definition: sim.h:172
const struct osim_file_desc * cwd
current working directory
Definition: sim.h:432
APDU command body.
Definition: sim.h:58
Definition: sim.h:96
const struct value_string ts102221_fcp_vals[14]
Definition: card_fs_uicc.c:191
osim_element_repr
Definition: sim.h:107
osim_element_type
Definition: sim.h:95
Definition: sim.h:363
Definition: sim.h:348
command header, no command data field, response data field (short)
Definition: sim.h:26
struct osim_decoded_data * decoded_data
Parsed/Decoded file contents.
Definition: sim.h:196
Definition: sim.h:272
osim_file_type
Definition: sim.h:141
enum osim_apdu_case apduc
command-response pair case, defining the encoding of Lc and Le
Definition: sim.h:32
struct osim_file_desc * osim_file_desc_find_aid(struct osim_file_desc *parent, const uint8_t *aid, uint8_t aid_len)
Definition: core.c:187
int osim_card_close(struct osim_card_hdl *card)
Definition: reader.c:284
Entry File.
Definition: sim.h:145
Definition: sim.h:345
Fixed-Size Record EF.
Definition: sim.h:152
Definition: sim.h:266
uint16_t u16
Definition: sim.h:124
size_t min
Minimum size of the file (transparent) or record in cyclic / linear file.
Definition: sim.h:181
uint32_t u32
Definition: sim.h:125
uint8_t u8
Definition: sim.h:123
struct osim_card_app_hdl * cur_app
currently selected application (if any)
Definition: sim.h:434
A card profile (e.g.
Definition: sim.h:321
const struct osim_card_sw * osim_cprof_find_sw(const struct osim_card_profile *cp, uint16_t sw_in)
Find status word within given card profile.
Definition: core.c:416
unsigned int atr_len
Definition: sim.h:423
const char * name
human-readable name
Definition: sim.h:302
char * osim_print_sw(const struct osim_chan_hdl *ch, uint16_t sw_in)
Definition: core.c:401
Definition: sim.h:373
enum osim_file_type type
Type of the file (EF, DF, ...)
Definition: sim.h:166
uint32_t proto_supported
Definition: sim.h:386
const struct osim_card_app_profile * osim_app_profile_find_by_aid(const uint8_t *aid, uint8_t aid_len)
Find any registered application profile based on its AID.
Definition: core.c:258
const char * name
Definition: sim.h:322
Definition: sim.h:344
struct msgb * osim_new_apdumsg(uint8_t cla, uint8_t ins, uint8_t p1, uint8_t p2, uint16_t lc, uint16_t le)
Generate an APDU message and initialize APDU command header.
Definition: core.c:324
Definition: sim.h:109
Definition: sim.h:161
struct osim_file_desc * adf
file system description
Definition: sim.h:307
Definition: sim.h:267
command header, command data field (short), no response data field
Definition: sim.h:28
#define MAX_AID_LEN
Definition: sim.h:11
const uint8_t * df_name
Definition: sim.h:171
Definition: sim.h:369
uint8_t p2
Parameter 2 byte.
Definition: sim.h:47
uint16_t lc
number of bytes in the command data field Nc, which will encoded in 0, 1 or 3 bytes into Lc...
Definition: sim.h:60
struct osim_file_ops __attribute__
Definition: sim.h:368
struct osim_file_desc * osim_file_desc_find_name(struct osim_file_desc *parent, const char *name)
Definition: core.c:175
struct osim_card_hdl * card
current card, if any
Definition: sim.h:389
A card status word (SW)
Definition: sim.h:279
Transparent EF.
Definition: sim.h:151
generic string
Definition: sim.h:101
struct msgb * encoded_data
Encoded file contents.
Definition: sim.h:194
struct osim_card_profile * prof
card profile
Definition: sim.h:411
uint8_t p3
Parameter 3 byte, used for TPDU by T=0.
Definition: sim.h:48
struct osim_file_desc * parent
parent DF
Definition: sim.h:164
A single instance of a file: Descriptor and contents.
Definition: sim.h:189
Definition: sim.h:110
enum osim_proto proto
card protocol
Definition: sim.h:413
BCD encoded digits.
Definition: sim.h:103
APDU/TPDU command header.
Definition: sim.h:43
const char * short_name
Short Name (like EF.ICCID)
Definition: sim.h:174
Definition: sim.h:142
char * osim_print_sw_buf(char *buf, size_t buf_len, const struct osim_chan_hdl *ch, uint16_t sw_in)
Definition: core.c:366
struct osim_reader_hdl * reader
reader through which card is accessed
Definition: sim.h:409
Definition: sim.h:346