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