Cipher, Identity and Protection Mechanisms

Typedefs | Functions
Cipher, Identity and Protection Mechanisms
Eet

Eet allows one to protect entries of an Eet_File individually. More...

## Typedefs
typedef struct _Eet_Key | Eet_Key
| Opaque handle that defines an identity (also known as key) in Eet's cipher system.
typedef int(* | Eet_Key_Password_Callback) (char *buffer, int size, int rwflag, void *data)
| Callback used to request if needed the password of a private key. More...

## Functions
EAPI Eet_Key * | eet_identity_open (const char *certificate_file, const char *private_key_file, Eet_Key_Password_Callback cb)
| Create an Eet_Key needed for signing an eet file. More...
EAPI void | eet_identity_close (Eet_Key *key)
| Close and release all resource used by an Eet_Key. More...
EAPI Eet_Error | eet_identity_set (Eet_File *ef, Eet_Key *key)
| Set a key to sign a file. More...
EAPI void | eet_identity_print (Eet_Key *key, FILE *out)
| Display both private and public key of an Eet_Key. More...
EAPI Eina_Bool | eet_identity_verify (Eet_File *ef, const char *certificate_file)
| Compare the identify certificate of an eet file against a stored one. More...
EAPI const void * | eet_identity_x509 (Eet_File *ef, int *der_length)
| Get the x509 der certificate associated with an Eet_File. More...
EAPI const void * | eet_identity_signature (Eet_File *ef, int *signature_length)
| Get the raw signature associated with an Eet_File. More...
EAPI const void * | eet_identity_sha1 (Eet_File *ef, int *sha1_length)
| Get the SHA1 associated with a file. More...
EAPI void | eet_identity_certificate_print (const unsigned char *certificate, int der_length, FILE *out)
| Display the x509 der certificate to out. More...

## Detailed Description

Eet allows one to protect entries of an Eet_File individually.

This may be used to ensure data was not tampered or that third party does not read your data.

See also
  Eet File Ciphered Main Functions
  Image Store and Load using a Cipher

## Typedef Documentation

## ◆ Eet_Key_Password_Callback

typedef int(* Eet_Key_Password_Callback) (char *buffer, int size, int rwflag, void *data)

Callback used to request if needed the password of a private key.

Parameters

  buffer | the buffer where to store the password.
  size | the maximum password size (size of buffer, including '\0').
  rwflag | if the buffer is also readable or just writable.
  data | currently unused, may contain some context in future.

Returns
  1 on success and password was set to `buffer`, 0 on failure.

Since
  1.2.0

## Function Documentation

## ◆ eet_identity_open()

EAPI Eet_Key* eet_identity_open | ( | const char * | certificate_file,
|  | const char * | private_key_file,
|  | Eet_Key_Password_Callback | cb
| ) |  |

Create an Eet_Key needed for signing an eet file.

The certificate should provide the public that match the private key. No verification is done to ensure that.

Parameters

  certificate_file | The file where to find the certificate.
  private_key_file | The file that contains the private key.
  cb | Function to callback if password is required to unlock private key.

Returns
  A key handle to use, or `NULL` on failure.

See also
  eet_identity_close()

Warning
  You need to compile signature support in EET.

Since
  1.2.0

References eina_file_close(), eina_file_map_all(), eina_file_map_free(), eina_file_open(), EINA_FILE_SEQUENTIAL, eina_file_size_get(), eina_mmap_safety_enabled_set(), EINA_TRUE, and emile_cipher_init().

## ◆ eet_identity_close()

EAPI void eet_identity_close | ( | Eet_Key * | key | ) |

Close and release all resource used by an Eet_Key.

An reference counter prevent it from being freed until all file using it are also closed.

Parameters

  key | the key handle to close and free resources.

Since
  1.2.0

References emile_cipher_init().

Referenced by eet_identity_print().

## ◆ eet_identity_set()

EAPI Eet_Error eet_identity_set | ( | Eet_File * | ef,
|  | Eet_Key * | key
| ) |  |

Set a key to sign a file.

Parameters

  ef | the file to set the identity.
  key | the key handle to set as identity.

Returns
  EET_ERROR_BAD_OBJECT if `ef` is invalid or EET_ERROR_NONE on success.

Since
  1.2.0

References EET_ERROR_BAD_OBJECT, and EET_ERROR_NONE.

## ◆ eet_identity_print()

EAPI void eet_identity_print | ( | Eet_Key * | key,
|  | FILE * | out
| ) |  |

Display both private and public key of an Eet_Key.

Parameters

  key | the handle to print.
  out | where to print.

Warning
  You need to compile signature support in EET.

Since
  1.2.0

References alloca(), EET_ERROR_BAD_OBJECT, EET_ERROR_MMAP_FAILED, EET_ERROR_NONE, EET_ERROR_NOT_IMPLEMENTED, EET_ERROR_OUT_OF_MEMORY, EET_ERROR_SIGNATURE_FAILED, EET_ERROR_WRITE_ERROR, EET_ERROR_X509_ENCODING_FAILED, eet_identity_close(), eina_mmap_safety_enabled_set(), EINA_TRUE, emile_cipher_init(), ERR, mmap(), and munmap().

## ◆ eet_identity_verify()

EAPI Eina_Bool eet_identity_verify | ( | Eet_File * | ef,
|  | const char * | certificate_file
| ) |  |

Compare the identify certificate of an eet file against a stored one.

Parameters

  ef | The file handle to check the identify of
  certificate_file | The path to the certificate file

Returns
  EINA_TRUE if the certificates match, otherwise EINA_FALSE;

The `ef` file handle mus be valid, and a signed file, otherwise checking will fail. The path to the certificate file must be a valid file path to a 'pem' format file (the same used for siging with eet_identity_open() as a certificate file).

Note
  This function can not be used to provide any security mecanism. You need to check your x509 certificate against a chain of trust to have a proper security. This is just a convenience test function.

Warning
  You need to compile signature support in EET.

Since
  1.13

References EINA_FALSE, and EINA_TRUE.

## ◆ eet_identity_x509()

EAPI const void* eet_identity_x509 | ( | Eet_File * | ef,
|  | int * | der_length
| ) |  |

Get the x509 der certificate associated with an Eet_File.

Will return NULL if the file is not signed.

Parameters

  ef | The file handle to query.
  der_length | The length of returned data, may be `NULL`.

Returns
  the x509 certificate or `NULL` on error.

Since
  1.2.0

## ◆ eet_identity_signature()

EAPI const void* eet_identity_signature | ( | Eet_File * | ef,
|  | int * | signature_length
| ) |  |

Get the raw signature associated with an Eet_File.

Will return NULL if the file is not signed.

Parameters

  ef | The file handle to query.
  signature_length | The length of returned data, may be `NULL`.

Returns
  the raw signature or `NULL` on error.

## ◆ eet_identity_sha1()

EAPI const void* eet_identity_sha1 | ( | Eet_File * | ef,
|  | int * | sha1_length
| ) |  |

Get the SHA1 associated with a file.

Could be the one used to sign the data or if the data where not signed, it will be the SHA1 of the file.

Parameters

  ef | The file handle to query.
  sha1_length | The length of returned data, may be `NULL`.

Returns
  the associated SHA1 or `NULL` on error.

Since
  1.2.0

## ◆ eet_identity_certificate_print()

EAPI void eet_identity_certificate_print | ( | const unsigned char * | certificate,
|  | int | der_length,
|  | FILE * | out
| ) |  |

Display the x509 der certificate to out.

Parameters

  certificate | the x509 certificate to print
  der_length | The length the certificate.
  out | where to print.

Warning
  You need to compile signature support in EET.

Since
  1.2.0

References alloca(), eina_binbuf_manage_new(), EINA_TRUE, emile_binbuf_cipher(), emile_cipher_init(), ERR, and INF.