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

Functions

Function Documentation

◆ agc_encrypt()

◆ agc_decrypt()

◆ agc_fencrypt()

◆ agc_fdecrypt()

◆ agc_to_b64()

◆ agc_from_b64()

◆ agc_version()

◆ agc_malloc()

◆ agc_free()