Loading...
Searching...
No Matches
lime_ffi.cpp File Reference

## Classes

struct | lime_manager_struct
| encapsulate a unique pointer to limeManager in an opaque structure More...
struct | lime_ffi_data_struct
| an opaque structure holding the lime cpp closure to be used to forward the X3DH server's response to lime More...

## Functions

static lime::CurveId | ffi2lime_CurveId (const enum lime_ffi_CurveId curve)
static enum lime_ffi_CallbackReturn | lime2ffi_CallbackReturn (const lime::CallbackReturn cbReturn)
static lime::EncryptionPolicy | ffi2lime_EncryptionPolicy (const enum lime_ffi_EncryptionPolicy encryptionPolicy)
static enum lime_ffi_PeerDeviceStatus | lime2ffi_PeerDeviceStatus (const lime::PeerDeviceStatus status)
static lime::PeerDeviceStatus | ffi2lime_PeerDeviceStatus (const enum lime_ffi_PeerDeviceStatus status)
int | lime_ffi_processX3DHServerResponse (lime_ffi_data_t userData, const int code, const uint8_t *response, const size_t response_size)
| Forward X3DH server response to the lime engine.
int | lime_ffi_manager_init (lime_manager_t *const manager, const char *db, const lime_ffi_X3DHServerPostData X3DH_post_data, void *userData)
| Initialise a Lime Manager, only one per end-point is required.
int | lime_ffi_create_user (lime_manager_t manager, const char *localDeviceId, const char *x3dhServerUrl, const enum lime_ffi_CurveId curve, const uint16_t OPkInitialBatchSize, const lime_ffi_Callback callback, void *callbackUserData)
| Insert a lime user in local base and publish him on the X3DH server.
int | lime_ffi_delete_user (lime_manager_t manager, const char *localDeviceId, const lime_ffi_Callback callback, void *callbackUserData)
| Delete a user from local database and from the X3DH server.
int | lime_ffi_is_user (lime_manager_t manager, const char *localDeviceId)
| Check if a user is present and active in local storage.
int | lime_ffi_encryptOutBuffersMaximumSize (const size_t plainMessageSize, const enum lime_ffi_CurveId curve, size_t *DRmessageSize, size_t *cipherMessageSize)
| Compute the maximum buffer sizes for the encryption outputs: DRmessage and cipherMessage.

int

lime_ffi_encrypt (lime_manager_t manager, const char *localDeviceId, const uint8_t *const recipientUserId, const size_t recipientUserIdSize, lime_ffi_RecipientData_t *const recipients, const size_t recipientsSize, const uint8_t *const plainMessage, const size_t plainMessageSize, uint8_t *const cipherMessage, size_t *cipherMessageSize, const lime_ffi_Callback callback, void *callbackUserData, enum lime_ffi_EncryptionPolicy encryptionPolicy)

| Encrypt a buffer (text or file) for a given list of recipient devices.
enum lime_ffi_PeerDeviceStatus | lime_ffi_decrypt (lime_manager_t manager, const char *localDeviceId, const uint8_t *const recipientUserId, const size_t recipientUserIdSize, const char *senderDeviceId, const uint8_t *const DRmessage, const size_t DRmessageSize, const uint8_t *const cipherMessage, const size_t cipherMessageSize, uint8_t *const plainMessage, size_t *plainMessageSize)
| Decrypt the given message.
int | lime_ffi_manager_destroy (lime_manager_t manager)
| Destroy the internal structure used to interact with lime.
int | lime_ffi_get_selfIdentityKey (lime_manager_t manager, const char *localDeviceId, uint8_t *const Ik, size_t *IkSize)
| retrieve self Identity Key, an EdDSA formatted public key
int | lime_ffi_set_peerDeviceStatus (lime_manager_t manager, const char *peerDeviceId, const uint8_t *const Ik, const size_t IkSize, enum lime_ffi_PeerDeviceStatus status)
| set the peer device status flag in local storage: unsafe, trusted or untrusted.
enum lime_ffi_PeerDeviceStatus | lime_ffi_get_peerDeviceStatus (lime_manager_t manager, const char *peerDeviceId)
| get the status of a peer device: unknown, untrusted, trusted, unsafe
int | lime_ffi_delete_peerDevice (lime_manager_t manager, const char *peerDeviceId)
| delete a peerDevice from local storage
int | lime_ffi_stale_sessions (lime_manager_t manager, const char *localDeviceId, const char *peerDeviceId)
| Stale all sessions between localDeviceId and peerDevice. If peerDevice keep using this session to encrypt and we decrypt with success, the session will be reactivated but to encrypt a message to this peerDevice, a new session will be created. If no session is active between the given device, this call has no effect.
int | lime_ffi_update (lime_manager_t manager, const char *localDeviceId, const lime_ffi_Callback callback, void *callbackUserData, uint16_t OPkServerLowLimit, uint16_t OPkBatchSize)
| Update: shall be called once a day at least, performs checks, updates and cleaning operations.
int | lime_ffi_set_x3dhServerUrl (lime_manager_t manager, const char *localDeviceId, const char *x3dhServerUrl)
| Set the X3DH key server URL for this identified user.
int | lime_ffi_get_x3dhServerUrl (lime_manager_t manager, const char *localDeviceId, char *x3dhServerUrl, size_t *x3dhServerUrlSize)
| Get the X3DH key server URL for this identified user.

## Detailed Description

Author
  Johan Pascal

Copyright
  Copyright (C) 2018 Belledonne Communications SARL

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

## Function Documentation

## ffi2lime_CurveId()

lime::CurveId ffi2lime_CurveId | ( | const enum lime_ffi_CurveId | curve | ) |

static

## ffi2lime_EncryptionPolicy()

lime::EncryptionPolicy ffi2lime_EncryptionPolicy | ( | const enum lime_ffi_EncryptionPolicy | encryptionPolicy | ) |

static

## ffi2lime_PeerDeviceStatus()

lime::PeerDeviceStatus ffi2lime_PeerDeviceStatus | ( | const enum lime_ffi_PeerDeviceStatus | status | ) |

static

## lime2ffi_CallbackReturn()

enum lime_ffi_CallbackReturn lime2ffi_CallbackReturn | ( | const lime::CallbackReturn | cbReturn | ) |

static

## lime2ffi_PeerDeviceStatus()

enum lime_ffi_PeerDeviceStatus lime2ffi_PeerDeviceStatus | ( | const lime::PeerDeviceStatus | status | ) |

static

## lime_ffi_create_user()

int lime_ffi_create_user | ( | lime_manager_t | manager,
|  | const char * | localDeviceId,
|  | const char * | x3dhServerUrl,
|  | const enum lime_ffi_CurveId | curve,
|  | const uint16_t | OPkInitialBatchSize,
|  | const lime_ffi_Callback | callback,
|  | void * | callbackUserData )

Insert a lime user in local base and publish him on the X3DH server.

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | localDeviceId | Identify the local user acount to use, it must be unique and is also be used as Id on the X3DH key server, it shall be the GRUU
  [in] | x3dhServerUrl | The complete url(including port) of the X3DH key server. It must connect using HTTPS. Example: https://sip5.linphone.org:25519
  [in] | curve | Choice of elliptic curve to use as base for ECDH and EdDSA operation involved. Can be lime_ffi_CurveId_c25519 or lime_ffi_CurveId_c448.
  [in] | OPkInitialBatchSize | Number of OPks in the first batch uploaded to X3DH server
  [in] | callback | This operation contact the X3DH server and is thus asynchronous, when server responds, this callback will be called giving the exit status and an error message in case of failure
  [in] | callbackUserData | this pointer will be forwarded to the callback as first parameter

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_decrypt()

enum lime_ffi_PeerDeviceStatus lime_ffi_decrypt | ( | lime_manager_t | manager,
|  | const char * | localDeviceId,
|  | const uint8_t *const | recipientUserId,
|  | const size_t | recipientUserIdSize,
|  | const char * | senderDeviceId,
|  | const uint8_t *const | DRmessage,
|  | const size_t | DRmessageSize,
|  | const uint8_t *const | cipherMessage,
|  | const size_t | cipherMessageSize,
|  | uint8_t *const | plainMessage,
|  | size_t * | plainMessageSize )

Decrypt the given message.

if specified localDeviceId is not found in local Storage, return an error

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | localDeviceId | used to identify which local acount to use and also as the recipient device ID of the message, shall be the GRUU
  [in] | recipientUserId | the Id of intended recipient, shall be a sip:uri of user or conference, is used as associated data to ensure no-one can mess with intended recipient it is not necessarily the sip:uri base of the GRUU as this could be a message from alice first device intended to bob being decrypted on alice second device
  [in] | recipientUserIdSize | the size of the previous buffer(this is used as Associated Data, so it could be actually anything)
  [in] | senderDeviceId | Identify sender Device. This field shall be extracted from signaling data in transport protocol, is used to rebuild the authenticated data associated to the encrypted message
  [in] | DRmessage | Double Ratchet message targeted to current device
  [in] | DRmessageSize | DRmessage buffer size
  [in] | cipherMessage | when present (depends on encryption policy) holds a common part of the encrypted message. Set to NULL if not present in the incoming message.
  [in] | cipherMessageSize | cipherMessage buffer size(set to 0 if no cipherMessage is present in the incoming message)
  [out] | plainMessage | the output buffer: its size shall be MAX(cipherMessageSize, DRmessageSize)
  [in,out] | plainMessageSize | plainMessage buffer size, updated with the actual size of the data written

Warning
  The plainMessage buffer must be large enough to store the decrypted message or we face the possibility to not ever be able to decrypt the message.(internal successful decryption will remove the ability to decrypt the same message again). To avoid problem the size of the plain message shall be MAX(cipherMessageSize, DRmessageSize) as:
  - The decrypted message is the same size of the encrypted one.
  - The encrypted message(not alone but we can afford the temporary usage of few dozens bytes) is stored either in cipherMessage or DRmessage depends on encrypter's choice
  - By allocating MAX(cipherMessageSize, DRmessageSize) bytes to the plainMessage buffer we ensure it can hold the decrypted message

Returns
  fail if we cannot decrypt the message, unknown when it is the first message we ever receive from the sender device, untrusted for known but untrusted sender device, or trusted if it is

## lime_ffi_delete_peerDevice()

int lime_ffi_delete_peerDevice | ( | lime_manager_t | manager,
|  | const char * | peerDeviceId )

delete a peerDevice from local storage

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | peerDeviceId | The device Id to be removed from local storage, shall be its GRUU

Call is silently ignored if the device is not found in local storage

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_delete_user()

int lime_ffi_delete_user | ( | lime_manager_t | manager,
|  | const char * | localDeviceId,
|  | const lime_ffi_Callback | callback,
|  | void * | callbackUserData )

Delete a user from local database and from the X3DH server.

if specified localDeviceId is not found in local Storage, return an error

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | localDeviceId | Identify the local user acount to use, it must be unique and is also be used as Id on the X3DH key server, it shall be the GRUU
  [in] | callback | This operation contact the X3DH server and is thus asynchronous, when server responds, this callback will be called giving the exit status and an error message in case of failure
  [in] | callbackUserData | this pointer will be forwarded to the callback as first parameter

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_encrypt()

int lime_ffi_encrypt | ( | lime_manager_t | manager,
|  | const char * | localDeviceId,
|  | const uint8_t *const | recipientUserId,
|  | const size_t | recipientUserIdSize,
|  | lime_ffi_RecipientData_t *const | recipients,
|  | const size_t | recipientsSize,
|  | const uint8_t *const | plainMessage,
|  | const size_t | plainMessageSize,
|  | uint8_t *const | cipherMessage,
|  | size_t * | cipherMessageSize,
|  | const lime_ffi_Callback | callback,
|  | void * | callbackUserData,
|  | enum lime_ffi_EncryptionPolicy | encryptionPolicy )

Encrypt a buffer (text or file) for a given list of recipient devices.

if specified localDeviceId is not found in local Storage, return an error

    Clarification on recipients:

    recipients information needed are a list of the device Id and one userId. The device Id shall be their GRUU while the userId is a sip:uri.

    recipient User Id is used to identify the actual intended recipient. Example: alice have two devices and is signed up on a conference having
    bob and claire as other members. The recipientUserId will be the conference sip:uri and device list will include:
         - alice other device
         - bob devices
         - claire devices
    If Alice write to Bob only, the recipientUserId will be bob sip:uri and recipient devices list :
         - alice other device
         - bob devices

    In all cases, the identified source of the message will be the localDeviceId

    If the X3DH server can't provide keys for a peer device, its status is set to fail and its DRmessageSize is 0. Other devices get their encrypted message
    If no peer device could get encrypted for all of them are missing keys on the X3DH server, the callback will be called with fail exit status

Note
  all buffers are allocated by caller. If a buffer is too small to get the data, the function will return an error.

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | localDeviceId | used to identify which local acount to use and also as the identified source of the message, shall be the GRUU
  [in] | recipientUserId | the Id of intended recipient, shall be a sip:uri of user or conference, is used as associated data to ensure no-one can mess with intended recipient
  [in] | recipientUserIdSize | the size of the previous buffer(this is used as Associated Data, so it could be actually anything)

  [in,out]

  recipients

  a list of RecipientData holding:
  - the recipient device Id(GRUU)
    - an allocated buffer large enough to store the DRmessage which must then be routed to that recipient
    - the size of this buffer, updated with the actual size written in it when the operation is completed(after callbackStatus is executed)
    - the peer Status. If peerStatus is set to fail, this entry is ignored otherwise the peerStatus is set by the encrypt, see lime_ffi_PeerDeviceStatus definition for details

  [in] | recipientsSize | how many recipients are in the recipients array
  [in] | plainMessage | a buffer holding the message to encrypt, can be text or data.
  [in] | plainMessageSize | size of the plainMessage buffer
  [out] | cipherMessage | points to the buffer to store the encrypted message which must be routed to all recipients(if one is produced, depends on encryption policy)
  [in,out] | cipherMessageSize | size of the cipherMessage buffer, is updated with the size of the actual data written in it
  [in] | callback | Performing encryption may involve the X3DH server and is thus asynchronous, when the operation is completed, this callback will be called giving the exit status and an error message in case of failure.
  [in] | callbackUserData | this pointer will be forwarded to the callback as first parameter
  [in] | encryptionPolicy | select how to manage the encryption: direct use of Double Ratchet message or encrypt in the cipher message and use the DR message to share the cipher message key default is optimized output size mode.

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_encryptOutBuffersMaximumSize()

int lime_ffi_encryptOutBuffersMaximumSize | ( | const size_t | plainMessageSize,
|  | const enum lime_ffi_CurveId | curve,
|  | size_t * | DRmessageSize,
|  | size_t * | cipherMessageSize )

Compute the maximum buffer sizes for the encryption outputs: DRmessage and cipherMessage.

Parameters

  [in] | plainMessageSize | size of the plain message to be encrypted
  [in] | curve | Choice of elliptic curve to use as base for ECDH and EdDSA operation involved. Can be lime_ffi_CurveId_c25519 or lime_ffi_CurveId_c448.
  [out] | DRmessageSize | maximum size of the DRmessage produced by the encrypt function
  [out] | cipherMessageSize | maximum size of the cipherMessage produced by the encrypt function

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_get_peerDeviceStatus()

enum lime_ffi_PeerDeviceStatus lime_ffi_get_peerDeviceStatus | ( | lime_manager_t | manager,
|  | const char * | peerDeviceId )

get the status of a peer device: unknown, untrusted, trusted, unsafe

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | peerDeviceId | The device Id of peer, shall be its GRUU

Returns
  unknown if the device is not in localStorage, untrusted, trusted or unsafe according to the stored value of peer device status flag otherwise

## lime_ffi_get_selfIdentityKey()

int lime_ffi_get_selfIdentityKey | ( | lime_manager_t | manager,
|  | const char * | localDeviceId,
|  | uint8_t *const | Ik,
|  | size_t * | IkSize )

retrieve self Identity Key, an EdDSA formatted public key

if specified localDeviceId is not found in local Storage, return an error

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | localDeviceId | used to identify which local account we're dealing with, shall be the GRUU
  [out] | Ik | the EdDSA public identity key, formatted as in RFC8032
  [in,out] | IkSize | size of the previous buffer, updated with the size of data actually written

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_get_x3dhServerUrl()

int lime_ffi_get_x3dhServerUrl | ( | lime_manager_t | manager,
|  | const char * | localDeviceId,
|  | char * | x3dhServerUrl,
|  | size_t * | x3dhServerUrlSize )

Get the X3DH key server URL for this identified user.

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | localDeviceId | Identify the local user account, it must be unique and is also be used as Id on the X3DH key server, it shall be the GRUU, in a NULL terminated string
  [in] | x3dhServerUrl | The complete url(including port) of the X3DH key server in a NULL terminated string
  [in,out] | x3dhServerUrlSize | Size of the previous buffer, is updated with actual size of data written(without the '\0', would give the same result as strlen.)

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_is_user()

int lime_ffi_is_user | ( | lime_manager_t | manager,
|  | const char * | localDeviceId )

Check if a user is present and active in local storage.

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | localDeviceId | used to identify which local account looking up, shall be the GRUU (Null terminated string)

Returns
  LIME_FFI_SUCCESS if the user is active in the local storage, LIME_FFI_USER_NOT_FOUND otherwise

## lime_ffi_manager_destroy()

int lime_ffi_manager_destroy | ( | lime_manager_t | manager | ) |

Destroy the internal structure used to interact with lime.

Parameters

  [in,out] | manager | pointer to the opaque structure used to interact with lime

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_manager_init()

int lime_ffi_manager_init | ( | lime_manager_t *const | manager,
|  | const char * | db,
|  | const lime_ffi_X3DHServerPostData | X3DH_post_data,
|  | void * | userData )

Initialise a Lime Manager, only one per end-point is required.

Parameters

  [out] | manager | pointer to the opaque structure used to interact with lime
  [in] | db | string used to access DB (shall be filename for sqlite3), directly forwarded to SOCI session opening
  [in] | X3DH_post_data | A function to send data to the X3DH server. The server response must be forwarded to lime using the lime_ffi_processX3DHServerResponse function
  [in] | userData | pointer passed back to the X3DH_post_data callback

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_processX3DHServerResponse()

int lime_ffi_processX3DHServerResponse | ( | lime_ffi_data_t | limeData,
|  | const int | code,
|  | const uint8_t * | response,
|  | const size_t | response_size )

Forward X3DH server response to the lime engine.

Parameters

  [in] | limeData | A pointer to an opaque structure used internally (provided by the X3DHServerPostData function)
  [in] | code | The response code given by X3DH server, connection is made through https, so we expect 200 for Ok
  [in] | response | binary buffered server response
  [in] | response_size | size of previous buffer

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_set_peerDeviceStatus()

int lime_ffi_set_peerDeviceStatus | ( | lime_manager_t | manager,
|  | const char * | peerDeviceId,
|  | const uint8_t *const | Ik,
|  | const size_t | IkSize,
|  | enum lime_ffi_PeerDeviceStatus | status )

set the peer device status flag in local storage: unsafe, trusted or untrusted.

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | peerDeviceId | The device Id of peer, shall be its GRUU
  [in] | Ik | the EdDSA peer public identity key, formatted as in RFC8032 (optionnal, needed only if status is trusted)
  [in] | IkSize | size of the previous buffer
  [in] | status | value of flag to set: accepted values are trusted, untrusted, unsafe

return an error if given key doesn't match the one present in local storage(if we have a key) if the status flag value is unexpected (not one of trusted, untrusted, unsafe), ignore the call if the status flag is unsafe or untrusted, ignore the value of Ik and call the version of this function without it

if peer Device is not present in local storage and status is trusted or unsafe, it is added, if status is untrusted, it is just ignored

General algorithm followed by the set_peerDeviceStatus functions

- Status is valid? (not one of trusted, untrusted, unsafe)? No: return
- status is trusted
  - We have Ik? -> No: return
  - Device is already in storage but Ik differs from the given one : exception
  - Insert/update in local storage
- status is untrusted
  - Ik is ignored
  - Device already in storage? No: return
  - Device already in storage but current status is unsafe? Yes: return
  - update in local storage -status is unsafe
  - ignore Ik
  - insert/update the status. If inserted, insert an invalid Ik

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_set_x3dhServerUrl()

int lime_ffi_set_x3dhServerUrl | ( | lime_manager_t | manager,
|  | const char * | localDeviceId,
|  | const char * | x3dhServerUrl )

Set the X3DH key server URL for this identified user.

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | localDeviceId | Identify the local user account, it must be unique and is also be used as Id on the X3DH key server, it shall be the GRUU
  [in] | x3dhServerUrl | The complete url(including port) of the X3DH key server. It must connect using HTTPS. Example: https://sip5.linphone.org:25519

Returns
  LIME_FFI_SUCCESS or a negative error code

## lime_ffi_stale_sessions()

int lime_ffi_stale_sessions | ( | lime_manager_t | manager,
|  | const char * | localDeviceId,
|  | const char * | peerDeviceId )

Stale all sessions between localDeviceId and peerDevice. If peerDevice keep using this session to encrypt and we decrypt with success, the session will be reactivated but to encrypt a message to this peerDevice, a new session will be created. If no session is active between the given device, this call has no effect.

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | localDeviceId | Identify the local user account, it must be unique and is also be used as Id on the X3DH key server, it shall be the GRUU
  [in] | peerDeviceId | The device Id of peer, shall be its GRUU

## lime_ffi_update()

int lime_ffi_update | ( | lime_manager_t | manager,
|  | const char * | localDeviceId,
|  | const lime_ffi_Callback | callback,
|  | void * | callbackUserData,
|  | uint16_t | OPkServerLowLimit,
|  | uint16_t | OPkBatchSize )

Update: shall be called once a day at least, performs checks, updates and cleaning operations.

- check if we shall update a new SPk to X3DH server(SPk lifetime is set in settings)
- check if we need to upload OPks to X3DH server
- remove old SPks, clean double ratchet sessions (remove staled, clean their stored keys for skipped messages)

Is performed for all users founds in local storage

Parameters

  [in] | manager | pointer to the opaque structure used to interact with lime
  [in] | localDeviceId | Identify the local user account, it must be unique and is also be used as Id on the X3DH key server, it shall be the GRUU
  [in] | callback | Performing encryption may involve the X3DH server and is thus asynchronous, when the operation is completed, this callback will be called giving the exit status and an error message in case of failure.
  [in] | callbackUserData | this pointer will be forwarded to the callback as first parameter
  [in] | OPkServerLowLimit | If server holds less OPk than this limit, generate and upload a batch of OPks
  [in] | OPkBatchSize | Number of OPks in a batch uploaded to server

Returns
  LIME_FFI_SUCCESS or a negative error code