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