Classes | Defines | Typedefs | Enumerations | Functions

aegis_crypto.h File Reference

Keyless cryptographic primitives. More...

Go to the source code of this file.

Classes

struct  aegis_signature_t
 A binary signature. More...
struct  aegis_digest_t
 A binary hash. More...

Defines

#define MAX_CRYPTO_INPUT_SIZE   4050
 The crypto operations are guaranteed to work in all environments at most with this long input buffer in functions aegis_crypto_sign, aegis_crypto_verify, aegis_crypto_encrypt and aegis_crypto_decrypt. The signing functions work with longer buffers, but they change the strategy by first computing a hash over the input data and then signing the hash. The encryption functions will return aegis_crypto_error with errno set as EINVAL, so you will just have to encrypt your data in smaller chunks than this.
#define SIGNATURE_LENGTH   20
 The length of a binary signature in bytes.
#define DIGESTLEN   20
 The length of the digest checksum used in integrity protection, currently SHA_DIGEST_LENGTH from openssl/sha.h.
#define SIGNATURE_STRING_LENGTH_HEX   40
 The length of a signature string in hexadecimal, less the terminating NUL.
#define SIGNATURE_STRING_LENGTH_BASE64   30
 The length of a signature string in base64 less the terminating NUL.
#define APPLICATION_ID   NULL
 Use this constant to make a signature with the application id.
#define AEGISFS_SGN_XATTR   ".aegisfs-signature"
 Any aegisfs mountpoint can be verified by help of this extended attribute. It is done by writing "token-name+newline+at-least-ten-bytes-of-random-data" to the attribute and then reading its value, which should be a valid signature made by the given token. If it is not, something funny is going on. Function aegis_crypto_verify_aegisfs implements this challenge/response check in one function.
#define AEGISFS_VFY_TOKEN   "aegisfs::aegisfs-verify"
 The AegisFS verification is made by this resource token.
#define AEGISFS_VFY_DATALEN   32
 When verifying aegisfs, exactly this many bytes of random data must be given to get the signature.
#define UNKNOWN_APP_ID   "unknown.unknown."
 The application id if there is no manifest for the package from which the binary comes from.

Typedefs

typedef struct aegis_signature_t AEGIS_SIGNATURE_T
 A synonym for "struct aegis_signature_t".
typedef struct aegis_digest_t AEGIS_DIGEST_T
 A synonym for "struct aegis_digest_t".

Enumerations

enum  aegis_system_mode_t { aegis_system_open, aegis_system_protected, aegis_system_emulated, aegis_system_plain }
 

The mode the system is in.

More...
enum  aegis_crypto_result { aegis_crypto_ok = 0, aegis_crypto_error, aegis_crypto_error_signature_missing, aegis_crypto_error_wrong_signature }
 

Error codes from various functions.

More...
enum  aegis_sysinvariant_t { sysinvariant_imei }
 

Supported system invariants These are system wide constant values that are not supposed to change uncontrollably.

More...
enum  aegis_format_t { aegis_as_hexstring, aegis_as_base64 }
 

Various textual forms for a signature.

More...

Functions

aegis_system_mode_t aegis_current_mode (void)
 In what mode the system seems to be in.
const char * aegis_system_invariant (aegis_sysinvariant_t invariant)
 Query the value of a given system invariant.
void aegis_application_id (pid_t of_pid, char **to_this)
 Return the application id of a given process.
void aegis_application_id_of_bin (const char *pathname, char **to_this)
 Return the application id of a given binary.
aegis_crypto_result aegis_crypto_sign (const RAWDATA_PTR data, const size_t nbrof_bytes, const char *with_token, struct aegis_signature_t *signature)
 Make a signature of a given data with a given resource token.
aegis_crypto_result aegis_crypto_verify (struct aegis_signature_t *signature, const char *with_token, const RAWDATA_PTR data, const size_t nbrof_bytes, aegis_system_mode_t *made_in_mode)
 Verify a signature.
size_t aegis_crypto_signature_to_string (struct aegis_signature_t *from, const aegis_format_t use_format, const char *token_name, char **to)
 Convert a binary signature into a human-readable string.
aegis_crypto_result aegis_crypto_string_to_signature (const char *from, struct aegis_signature_t *to, char **token_name)
 Convert a signature string into the binary format.
aegis_crypto_result aegis_crypto_free (RAWDATA_PTR ptr)
 Release a piece of memory allocated by some of the other functions.
aegis_crypto_result aegis_crypto_encrypt (const RAWDATA_PTR plaintext, const size_t nbrof_bytes, const char *token_name, RAWDATA_RPTR ciphertext, size_t *result_size)
 Encrypt a piece of memory.
aegis_crypto_result aegis_crypto_decrypt (const RAWDATA_PTR ciphertext, const size_t nbrof_bytes, const char *token_name, RAWDATA_RPTR plaintext, size_t *result_size)
 Decrypt a piece of memory.
const char * aegis_crypto_last_error_str (void)
 Return a description of the last error detected.
int aegis_crypto_init (void)
 Initialize the cryptofunctions.
void aegis_crypto_finish (void)
 Finish the cryptofunctions.
ssize_t aegis_crypto_random (RAWDATA_PTR to_buf, size_t bytes)
 Generate random bytes.
size_t aegis_crypto_new_symkey (RAWDATA_RPTR to_buf)
 Generate a new symmetric encryption key.
size_t aegis_crypto_symkeylen (void)
 Return the length of a symmetric encryption key.
aegis_crypto_result aegis_crypto_sign_file (const char *pathname, const void *data, const size_t len, const char *with_token)
 Make a signature of a given file with a given resource token.
aegis_crypto_result aegis_crypto_verify_file (const char *pathname, const void *data, const size_t len, const char *with_token)
 Verify a signature of a distinct file.
aegis_crypto_result aegis_crypto_verify_aegisfs (const char *dir, aegis_system_mode_t *cmode)
 Verify that the given directory is an AegisFS mountpoint.

Detailed Description

Keyless cryptographic primitives.

The underlying algorithms are subject to change. The scope of the operations is limited in one device: a signature made in one device cannot be verified in another device and data encrypted in one device cannot be decrypted in another device.

Also the mode in which the device is limits the scope. Data encrypted in the closed mode cannot be decrypted in the open mode. Other than that the operations work across modes. There is a special status code for a signature made in the other mode.


Enumeration Type Documentation

Error codes from various functions.

Use function aegis_crypto_last_error_str to get detailed information about the error.

Enumerator:
aegis_crypto_ok 

No errors detected

aegis_crypto_error 

Miscellaneous, use errno and aegis_crypto_last_error_str to get details

aegis_crypto_error_signature_missing 

Signature could not be found

aegis_crypto_error_wrong_signature 

Signature mismatch

Various textual forms for a signature.

Enumerator:
aegis_as_hexstring 

As a hex-string, using characters 0-9 and a-f

aegis_as_base64 

As base64

Supported system invariants These are system wide constant values that are not supposed to change uncontrollably.

Enumerator:
sysinvariant_imei 

The IMEI code of the device

The mode the system is in.

"Open" means that that the integrity cannot be guaranteed, as for instance the kernel may have been modified. "Protected" means that the system integrity is guaranteed. "Plain" means that the security frameowrk is not active, no integrity is guaranteed and not all functions can be used.

Enumerator:
aegis_system_open 

Integrity cannot be guaranteed

aegis_system_protected 

Integrity should be guaranteed

aegis_system_emulated 

Using the TEE emulator

aegis_system_plain 

No security framework available


Function Documentation

void aegis_application_id ( pid_t  of_pid,
char **  to_this 
)

Return the application id of a given process.

Parameters:
of_pid (in) the process id
to_this (out) the application id as a NUL-terminated string. Use aegis_crypto_free to release when no longer needed.
void aegis_application_id_of_bin ( const char *  pathname,
char **  to_this 
)

Return the application id of a given binary.

Parameters:
pathname (in) the pathname of a binary executable
to_this (out) the application id as a NUL-terminated string. Use aegis_crypto_free to release when no longer needed.
aegis_crypto_result aegis_crypto_decrypt ( const RAWDATA_PTR  ciphertext,
const size_t  nbrof_bytes,
const char *  token_name,
RAWDATA_RPTR  plaintext,
size_t *  result_size 
)

Decrypt a piece of memory.

Parameters:
ciphertext (in) The encrypted data to be decrypted
nbrof_bytes (in) The length of the encrypted data
token_name (in) The resource token to decrypt with. The calling process must possess this token.
plaintext (out) A pointer to the plaintext data. Use aegis_crypto_free to release when no longer needed.
result_size (out) The number of bytes in the plaintext.
Returns:
OK or an error * Caller must have the given token_name
aegis_crypto_result aegis_crypto_encrypt ( const RAWDATA_PTR  plaintext,
const size_t  nbrof_bytes,
const char *  token_name,
RAWDATA_RPTR  ciphertext,
size_t *  result_size 
)

Encrypt a piece of memory.

Parameters:
plaintext (in) The data to be encrypted
nbrof_bytes (in) The number of bytes to encrypt
token_name (in) The resource token to encrypt with. The calling process must possess this token.
ciphertext (out) A pointer to the encrypted data. Use aegis_crypto_free to release when no longer needed.
result_size (out) The number of bytes in the ciphertext
Returns:
OK or an error * Caller must have the given token_name
void aegis_crypto_finish ( void   ) 

Finish the cryptofunctions.

Again, it is not necessary to call this function, as it is installed as an atexit callback when aegis_crypto_init is called. You can call it for symmetry if you have also called aegis_crypto_init explicitly or to release some resources early. If other crypto functions are called after this the cryptofunctions will get re-initialized automatically.

aegis_crypto_result aegis_crypto_free ( RAWDATA_PTR  ptr  ) 

Release a piece of memory allocated by some of the other functions.

Parameters:
ptr (in) A pointer to the piece of memory
int aegis_crypto_init ( void   ) 

Initialize the cryptofunctions.

Returns:
1 when success, 0 when failure. application-id The calling process must have an application id, i.e. it must come from a signed package with a security manifest and mentioned in the manifest or inherit the application id from a parent process.

It is not absolutely necessary to call this function, as calling any other function will cause it being called automatically. If your application has a well-defined entry point (main or similar), it is good to call this explicitly to catch possible errors.

AID::* Must have an application id

const char* aegis_crypto_last_error_str ( void   ) 

Return a description of the last error detected.

Returns:
A text describing the last error, including source file name and a line number.

Call this function immediately after an error. Calling any other crypto function before this function may change the information.

size_t aegis_crypto_new_symkey ( RAWDATA_RPTR  to_buf  ) 

Generate a new symmetric encryption key.

Parameters:
to_buf (out) The new symmetric key
Returns:
The length of the new key

This function is for internal use only. Basically it just returns random bytes.

ssize_t aegis_crypto_random ( RAWDATA_PTR  to_buf,
size_t  bytes 
)

Generate random bytes.

Parameters:
to_buf (in) A pointer to the buffer that must hold at least the given number of bytes
bytes (in) How many bytes to create
Returns:
The number of random bytes returned. Should be equal to the given amount, -1 in case of error.
aegis_crypto_result aegis_crypto_sign ( const RAWDATA_PTR  data,
const size_t  nbrof_bytes,
const char *  with_token,
struct aegis_signature_t signature 
)

Make a signature of a given data with a given resource token.

Parameters:
data (in) A pointer to the data to be signed
nbrof_bytes (in) The number of bytes to be signed
with_token (in) The name (a NUL-terminated string) to make the signature with, or APPLICATION_ID (i.e. NULL) for the calling process's application id. To use a token one must possess it.
signature (out) The signature in the binary form
Returns:
OK or an error * Caller must have the given with_token
aegis_crypto_result aegis_crypto_sign_file ( const char *  pathname,
const void *  data,
const size_t  len,
const char *  with_token 
)

Make a signature of a given file with a given resource token.

Parameters:
pathname (in) The filename to be signed
data (in) The data to be written into the file. If NULL, the current file contents are signed.
len (in) If data is not NULL, how many bytes are written
with_token (in) The name (a NULL-terminated string) to make the signature with, or APPLICATION_ID for the calling process's application id. To use a token one must possess it.
Returns:
OK or an error * Caller must have the given with_token
size_t aegis_crypto_signature_to_string ( struct aegis_signature_t from,
const aegis_format_t  use_format,
const char *  token_name,
char **  to 
)

Convert a binary signature into a human-readable string.

Parameters:
from (in) The signature in the binary form
use_format (in) What encoding to use
token_name (in) If given, will be embedded in the signature. This makes the result string variable length
to (out) The result string as a NUL terminated string. Use aegis_crypto_free to release
Returns:
The length of the result string, less the terminating NUL
aegis_crypto_result aegis_crypto_string_to_signature ( const char *  from,
struct aegis_signature_t to,
char **  token_name 
)

Convert a signature string into the binary format.

Parameters:
from (in) The NUL-terminated string to be converted
to (out) The signature in the binary form
token_name (out) The token name, if it was included in the signature string. A NUL-terminated string, use aegis_crypto_free to release.
Returns:
OK or an error
size_t aegis_crypto_symkeylen ( void   ) 

Return the length of a symmetric encryption key.

Returns:
Number of bytes in the key

This function is for internal use only.

aegis_crypto_result aegis_crypto_verify ( struct aegis_signature_t signature,
const char *  with_token,
const RAWDATA_PTR  data,
const size_t  nbrof_bytes,
aegis_system_mode_t made_in_mode 
)

Verify a signature.

Parameters:
signature (in) The signature to be verified in the binary form
with_token (in) The resource token the signature was made with. One does not need to possess a token to be able to verify.
data (in) The data the signature was made of
nbrof_bytes (in) The number of bytes in the data
made_in_mode (out) In which mode the signature was made in
Returns:
OK or an error
aegis_crypto_result aegis_crypto_verify_aegisfs ( const char *  dir,
aegis_system_mode_t cmode 
)

Verify that the given directory is an AegisFS mountpoint.

Parameters:
dir (in) Name of the directory
cmode (out) On ouput, the variable tells in which mode the security framework is on. If the mode is open, take the result with a grain of salt.
Returns:
0 if the result is positive, an error number otherwise

Use this function to verify that a directory is mounted by the AegisFS cryptofilesystem. If the result is positive and the returned mode is protected, you should be good to go. Otherwise you might want to reconsider whether you want to store sensitive data in this directory or rely on the integrity of its contents.

This function can be used for all types of aegisfs mountpoints regardless of their type and access rights.

aegis_crypto_result aegis_crypto_verify_file ( const char *  pathname,
const void *  data,
const size_t  len,
const char *  with_token 
)

Verify a signature of a distinct file.

Parameters:
pathname (in) The filename the signature was made of
data (in) The data supposed to be in the file. If NULL, the current file contents are verified.
len (in) If data is not NULL, how many bytes are verified.
with_token (in) The resource with which the signature must have made with.
Returns:
OK or an error
aegis_system_mode_t aegis_current_mode ( void   ) 

In what mode the system seems to be in.

Returns:
The current mode.

Notice that this function cannot be fully trusted, as it is possible to fool the system to believe that it is in protected mode even if it is not by a custom kernel and by emulating BB5 functions, or simply be replacing this very function. It should be used only as a guideline.

const char* aegis_system_invariant ( aegis_sysinvariant_t  invariant  ) 

Query the value of a given system invariant.

Returns:
The value of the invariant as a NUL-terminated string