README.md
1# libese
2
3Document last updated: 13 Jan 2017
4
5## Introduction
6
7libese provides a minimal transport wrapper for communicating with
8embedded secure elements. Embedded secure elements typically adhere
9to smart card standards whose translation is not always smooth when
10migrated to an always connected bus, like SPI. The interfaces
11exposed by libese should enable higher level "terminal" implementations
12to be written on top and/or a service which provides a similar
13interface.
14
15Behind the interface, libese should help smooth over the differences
16between eSEs and smart cards use in the hardware adapter
17implementations. Additionally, a T=1 implementation is supplied,
18as it appears to be the most common wire transport for these chips.
19
20## Usage
21
22Public client interface for Embedded Secure Elements.
23
24Prior to use in a file, import all necessary variables with:
25
26 ESE_INCLUDE_HW(SOME_HAL_IMPL);
27
28Instantiate in a function with:
29
30 ESE_DECLARE(my_ese, SOME_HAL_IMPL);
31
32or
33
34 struct EseInterface my_ese = ESE_INITIALIZER(SOME_HAL_IMPL);
35
36or
37
38 struct EseInterface *my_ese = malloc(sizeof(struct EseInterface));
39 ...
40 ese_init(my_ese, SOME_HAL_IMPL);
41
42To initialize the hardware abstraction, call:
43
44 ese_open(my_ese);
45
46To release any claimed resources, call
47
48 ese_close(my_ese)
49
50when interface use is complete.
51
52To perform a transmit-receive cycle, call
53
54 ese_transceive(my_ese, ...);
55
56with a filled transmit buffer with total data length and
57an empty receive buffer and a maximum fill length.
58A negative return value indicates an error and a hardware
59specific code and string may be collected with calls to
60
61 ese_error_code(my_ese);
62 ese_error_message(my_ese);
63
64The EseInterface is not safe for concurrent access.
65(Patches welcome! ;).
66
67# Components
68
69libese is broken into multiple pieces:
70 * libese
71 * libese-sysdeps
72 * libese-hw
73 * libese-teq1
74
75*libese* provides the headers and wrappers for writing libese clients
76and for implementing hardware backends. It depends on a backend being
77provided as per *libese-hw* and on *libese-sysdeps*.
78
79*libese-sysdeps* provides the system level libraries that are needed by
80libese provided software. If libese is being ported to a new environment,
81like a bootloader or non-Linux OS, this library may need to be replaced.
82(Also take a look at libese/include/ese/log.h for the macro definitions
83 that may be needed.)
84
85*libese-hw* provides existing libese hardware backends.
86
87*libese-teq1* provides a T=1 compatible transcieve function that may be
88used by a hardware backend. It comes with some prequisites for use,
89such as a specifically structured set of error messages and
90EseInteface pad usage, but otherwise it does not depends on any specific
91functionality not abstracted via the libese EseOperations structure.
92
93
94## Supported backends
95
96There are two test backends, fake and echo, as well as one
97real backend for the NXP PN80T/PN81A.
98
99The NXP backends support both a direct kernel driver and
100a Linux SPIdev interface.
101