libagentcrypt: libagentcrypt.h File Reference

libagentcrypt 1.0.6

Functions
libagentcrypt.h File Reference

## Functions
int | agc_encrypt (const char *agent, const char *key_sha256, const uint8_t *cleartext, size_t cleartext_size, size_t pad_size, uint8_t **ciphertext, size_t *ciphertext_size)
| Encrypt and authenticate a block of data, for later decryption by agc_decrypt() More...
int | agc_decrypt (const char *agent, const uint8_t *ciphertext, size_t ciphertext_size, uint8_t **cleartext, size_t *cleartext_size)
| Decrypt and verify a block of data encrypted by agc_encrypt() More...
int | agc_fencrypt (const char *agent, const char *key_sha256, FILE *f_cleartext, FILE *f_ciphertext)
| Encrypt a file for later decryption by agc_fdecrypt() More...
int | agc_fdecrypt (const char *agent, FILE *f_ciphertext, FILE *f_cleartext)
| Decrypt a file encrypted by agc_fencrypt() More...
int | agc_to_b64 (const uint8_t *in, size_t in_size, char **out, size_t *out_size)
| Encode a block of data into a string (base64 format with no padding) More...
int | agc_from_b64 (const char *in, uint8_t **out, size_t *out_size)
| Decode a string (base64 format with no padding) to a block of data. More...
int | agc_version (void)
| Return the library version. More...
void * | agc_malloc (size_t size)
| Dynamically allocate and lock a secure buffer. More...
void | agc_free (void *buf, size_t size)
| Zero fill, unlock and free a dynamically allocated secure buffer. More...

## Function Documentation

## ◆ agc_encrypt()

int agc_encrypt | ( | const char * | agent,
|  | const char * | key_sha256,
|  | const uint8_t * | cleartext,
|  | size_t | cleartext_size,
|  | size_t | pad_size,
|  | uint8_t ** | ciphertext,
|  | size_t * | ciphertext_size
| ) |  |

Encrypt and authenticate a block of data, for later decryption by agc_decrypt()

Parameters

  [in] | agent | The ssh-agent UNIX domain socket bind address. If NULL the content of the SSH_AUTH_SOCK environment variable is used instead.
  [in] | key_sha256 | Pointer to a string containing the SHA256 fingerprint of the SSH key to be used for encryption. This can be obtained by running the following command (openssh >= 6.8 required):
      ssh-add -E sha256 -l
  The string may or may not begin with "SHA256:" The first key whose fingerprint starts with the string specified is selected. If NULL the first key is chosen automatically. Only RSA and ED25519 keys are supported. When using RSA keys, if the AGENTCRYPT_LEGACY environment variable is defined and not zero, RSA SHA1 signatures are used for encryption. This is not recommended and is only necessary if the encrypted data need to be decrypted using legacy openssh versions (older than 7.2) whose agent did not support RSA SHA256 signatures. Note that data encrypted using such legacy versions can always be decrypted correctly without needing to define this variable.
  [in] | cleartext | Pointer to the data to be encrypted.
  [in] | cleartext_size | Size of data to be encrypted.
  [in] | pad_size | Padding size. A chunk of random data no larger than pad_size is added at the end of cleartext, such that the combined cleartext and pad size is a non-zero integer multiple of pad_size. A minimum of 16 is enforced if pad_size < 16.
  [out] | ciphertext | This function allocates the output data buffer dynamically and it stores a pointer to it into *ciphertext upon success. The buffer MUST be freed by calling agc_free() after use. Do NOT use the standard free() function.
  [out] | ciphertext_size | The size of the output buffer is stored into *ciphertext_size.

Returns
  0 upon success, -1 otherwise. Reasons for failure include
  - the ssh key is not available: errno is set to ENOKEY
  - invalid data returned by ssh-agent: errno is set to EBADMSG
  - failure to allocate memory: errno is set to ENOMEM
  - invalid parameters: errno is set to EINVAL
  - any other C library error, including socket errors while communicating with ssh-agent: errno is left at the value set by the C library

## ◆ agc_decrypt()

int agc_decrypt | ( | const char * | agent,
|  | const uint8_t * | ciphertext,
|  | size_t | ciphertext_size,
|  | uint8_t ** | cleartext,
|  | size_t * | cleartext_size
| ) |  |

Decrypt and verify a block of data encrypted by agc_encrypt()

Parameters

  [in] | agent | The ssh-agent UNIX domain socket bind address. If NULL the content of the SSH_AUTH_SOCK environment variable is used instead.
  [in] | ciphertext | Pointer to the data to be decrypted.
  [in] | ciphertext_size | Size of the data to be decrypted.
  [out] | cleartext | This function allocates the output data buffer dynamically and it stores a pointer to it into *cleartext upon success. The buffer MUST be freed by calling agc_free() after use. Do NOT use the standard free() function.
  [out] | cleartext_size | The size of the output buffer is stored into *ciphertext_size upon success.

Returns
  0 upon success, -1 otherwise. Reasons for failure include
  - the ssh key required to decrypt is not available: errno is set to ENOKEY
  - invalid data returned by ssh-agent or failure to decrypt: errno is set to EBADMSG
  - failure to allocate memory: errno is set to ENOMEM
  - invalid parameters: errno is set to EINVAL
  - any other C library error, including socket errors while communicating with ssh-agent: errno is left at the value set by the C library

## ◆ agc_fencrypt()

int agc_fencrypt | ( | const char * | agent,
|  | const char * | key_sha256,
|  | FILE * | f_cleartext,
|  | FILE * | f_ciphertext
| ) |  |

Encrypt a file for later decryption by agc_fdecrypt()

Parameters

  [in] | agent | The ssh-agent UNIX domain socket bind address. If NULL the content of the SSH_AUTH_SOCK environment variable is used instead.
  [in] | key_sha256 | Pointer to a string containing the SHA256 fingerprint of the SSH key to be used for encryption. This can be obtained by running the following command (openssh >= 6.8 required):
      ssh-add -E sha256 -l
  The string may or may not begin with "SHA256:" The first key whose fingerprint starts with the string specified is selected. If NULL the first key is chosen automatically. Only RSA and ED25519 keys are supported.
  [in] | f_cleartext | Pointer to the input stream. Cleartext is read from this stream.
  [in] | f_ciphertext | Pointer to the output stream. Ciphertext is written to this stream. Invalid data may have already been written to the output stream when an error is detected. Therefore it may be advisable to use a temporary file for output and delete it upon failure.

Returns
  0 upon success, -1 otherwise. Reasons for failure include
  - the ssh key is not available: errno is set to ENOKEY
  - invalid data returned by ssh-agent: errno is set to EBADMSG
  - failure to allocate memory: errno is set to ENOMEM
  - invalid parameters: errno is set to EINVAL
  - any other C library error, including socket errors while communicating with ssh-agent or file errors: errno is left at the value set by the C library

## ◆ agc_fdecrypt()

int agc_fdecrypt | ( | const char * | agent,
|  | FILE * | f_ciphertext,
|  | FILE * | f_cleartext
| ) |  |

Decrypt a file encrypted by agc_fencrypt()

Parameters

  [in] | agent | The ssh-agent UNIX domain socket bind address. If NULL the content of the SSH_AUTH_SOCK environment variable is used instead.
  [in] | f_ciphertext | Pointer to the input stream. Ciphertext is read from this stream.
  [in] | f_cleartext | Pointer to the output stream. Cleartext is written to this stream. Invalid data may have already been written to the output stream when an error is detected. Therefore it may be advisable to use a temporary file for output and delete it upon failure.

Returns
  0 upon success, -1 otherwise. Reasons for failure include
  - the ssh key required to decrypt is not available: errno is set to ENOKEY
  - invalid data returned by ssh-agent or failure to decrypt: errno is set to EBADMSG
  - failure to allocate memory: errno is set to ENOMEM
  - invalid parameters: errno is set to EINVAL
  - any other C library error, including socket errors while communicating with ssh-agent or file errors: errno is left at the value set by the C library

## ◆ agc_to_b64()

int agc_to_b64 | ( | const uint8_t * | in,
|  | size_t | in_size,
|  | char ** | out,
|  | size_t * | out_size
| ) |  |

Encode a block of data into a string (base64 format with no padding)

Parameters

  [in] | in | Pointer to the data to be encoded.
  [in] | in_size | Size of the data to be encoded.
  [out] | out | This function allocates the output data buffer dynamically and it stores a pointer to it into *out upon success. The buffer MUST be freed by calling agc_free() after use. Do NOT use the standard free() function.
  [out] | out_size | The size of the output buffer is stored into *out_size upon success.

Returns
  0 upon success, -1 otherwise.

## ◆ agc_from_b64()

int agc_from_b64 | ( | const char * | in,
|  | uint8_t ** | out,
|  | size_t * | out_size
| ) |  |

Decode a string (base64 format with no padding) to a block of data.

Parameters

  [in] | in | Pointer to a NULL terminated input string
  [out] | out | This function allocates the output data buffer dynamically and it stores a pointer to it into *out upon success. The buffer MUST be freed by calling agc_free() after use. Do NOT use the standard free() function.
  [out] | out_size | The size of the output buffer is stored into *out_size upon success.

Returns
  0 upon success, -1 otherwise.

## ◆ agc_version()

int agc_version | ( | void |  | ) |

Return the library version.

Returns
  an integer encoding the library version as 0xMMmmuu00 (MM=major, mm=minor, uu=micro)

## ◆ agc_malloc()

void* agc_malloc | ( | size_t | size | ) |

Dynamically allocate and lock a secure buffer.

Parameters

  [in] | size | Size of buffer

Returns
  pointer to buffer upon success, NULL otherwise. The buffer MUST be freed by calling agc_free() after use. Do NOT use the standard free() function.

## ◆ agc_free()

void agc_free | ( | void * | buf,
|  | size_t | size
| ) |  |

Zero fill, unlock and free a dynamically allocated secure buffer.

Parameters

  [in] | buf | Pointer to buffer. If NULL no action is taken.
  [in] | size | Size of buffer. It MUST match the buffer size