Security functions

All functions related to encryption and encoding go here. More...

Data Structures
struct	hash_t
	Hash data structure. More...
Enumerations
enum	GGZTLSType { GGZ_TLS_CLIENT, GGZ_TLS_SERVER }
	TLS operation mode. More...
enum	GGZTLSVerificationType { GGZ_TLS_VERIFY_NONE, GGZ_TLS_VERIFY_PEER }
	TLS verification type. More...
Functions
hash_t	ggz_hash_create (const char *algo, const char *text)
	Create a hash over a text.
hash_t	ggz_hmac_create (const char *algo, const char *text, const char *secret)
	Create a HMAC hash over a text.
char *	ggz_base16_encode (const char *text, int length)
	Encodes text to base16.
char *	ggz_base64_encode (const char *text, int length)
	Encodes text to base64.
char *	ggz_base64_decode (const char *text, int length)
	Decodes text from base64.
void	ggz_tls_init (const char *certfile, const char *keyfile, const char *password)
	Initialize TLS support on the server side.
int	ggz_tls_support_query (void)
	Check TLS support.
const char *	ggz_tls_support_name (void)
	Name of the TLS implementation.
int	ggz_tls_enable_fd (int fdes, GGZTLSType whoami, GGZTLSVerificationType verify)
	Enable TLS for a file descriptor.
int	ggz_tls_disable_fd (int fdes)
	Disable TLS for a file descriptor.
size_t	ggz_tls_write (int fd, void *ptr, size_t n)
	Write some bytes to a secured file descriptor.
size_t	ggz_tls_read (int fd, void *ptr, size_t n)
	Read from a secured file descriptor.

---

Detailed Description

All functions related to encryption and encoding go here.

Encryption functions use gcrypt, and will always fail if support for gcrypt has not been compiled in. Encoding functions will always be available.

---

Enumeration Type Documentation

enum GGZTLSType

TLS operation mode.

Hints whether the TLS handshake will happen in either client or server mode.

See also:

ggz_tls_enable_fd

Enumerator:

GGZ_TLS_CLIENT	Operate as client.
GGZ_TLS_SERVER	Operate as server.

enum GGZTLSVerificationType

TLS verification type.

The authentication (verification) model to be used for the handshake. None means that no certificate is validated.

See also:

ggz_tls_enable_fd

Enumerator:

GGZ_TLS_VERIFY_NONE	Don't perform verification.
GGZ_TLS_VERIFY_PEER	Perform validation of the server's cert.

---

Function Documentation

hash_t ggz_hash_create	(	const char *	algo,
		const char *	text
	)

Create a hash over a text.

A hash sum over a given text is created, using the given algorithm. Space is allocated as needed.

Parameters:

	algo	The algorithm, like md5 or sha1
	text	Plain text used to calculate the hash sum

Returns:

Hash value in a structure

hash_t ggz_hmac_create	(	const char *	algo,
		const char *	text,
		const char *	secret
	)

Create a HMAC hash over a text.

Creates a hash sum using a secret key. Space is allocated as needed and must be freed afterwards.

Parameters:

	algo	The algorithm to use, like md5 or sha1
	text	Plain text used to calculate the hash sum
	secret	Secret key to be used for the HMAC creation

Returns:

Hash value in a structure

char* ggz_base16_encode	(	const char *	text,
		int	length
	)

Encodes text to base16.

Plain text with possibly unsafe characters is converted to the base16 (hex) format through this function. The returned string is allocated internally and must be freed.

Parameters:

	text	Plain text to encode
	length	Length of the text (which may contain binary characters), in bytes

Returns:

Base16 representation of the text

char* ggz_base64_encode	(	const char *	text,
		int	length
	)

Encodes text to base64.

Plain text with possibly unsafe characters is converted to the base64 format through this function. The returned string is allocated internally and must be freed.

Parameters:

	text	Plain text to encode
	length	Length of the text (which may contain binary characters), in bytes

Returns:

Base64 representation of the text

char* ggz_base64_decode	(	const char *	text,
		int	length
	)

Decodes text from base64.

This is the reverse function to ggz_base64_encode(). It will also allocate space as needed.

Parameters:

	text	Text in base64 format
	length	Length of the text, in bytes

Returns:

Native representation, may contain binary characters

void ggz_tls_init	(	const char *	certfile,
		const char *	keyfile,
		const char *	password
	)

Initialize TLS support on the server side.

This function sets up the necessary initialization values. It must be called by both the client and the server before any other TLS operations can take place. The client can pass NULL values for all parameters.

Parameters:

	certfile	File containing the certificate, or NULL
	keyfile	File containing the private key, or NULL
	password	Password to the private key, or NULL

int ggz_tls_support_query

(

void

)

Check TLS support.

Checks if real TLS support is available or communication will fall back to unencrypted connections. Even in the case of support, individual connections might still be unencrypted if the handshake fails.

Returns:

1 if TLS is supported, 0 if no support is present

See also:

ggz_tls_enable_fd

const char* ggz_tls_support_name

(

void

)

Name of the TLS implementation.

Returns the name of the TLS layer implementation used to encrypt connections.

Returns:

TLS implementation name, or NULL if no TLS support is present

See also:

ggz_tls_support_query

int ggz_tls_enable_fd	(	int	fdes,
		GGZTLSType	whoami,
		GGZTLSVerificationType	verify
	)

Enable TLS for a file descriptor.

A TLS handshake is performed for an existing connection on the given file descriptor. On success, all consecutive data will be encrypted.

Parameters:

	fdes	File descriptor in question
	whoami	Operation mode (client or server)
	verify	Verification mode

Returns:

1 on success, 0 on failure

int ggz_tls_disable_fd

(

int

fdes

)

Disable TLS for a file descriptor.

An existing TLS connection is reset to a normal connection on which all communication happens without encryption.

Parameters:

fdes

File descriptor in question

Returns:

1 on success, 0 on failure

size_t ggz_tls_write	(	int	fd,
		void *	ptr,
		size_t	n
	)

Write some bytes to a secured file descriptor.

This function acts as a TLS-aware wrapper for write(2).

Parameters:

	fd	File descriptor to use
	ptr	Pointer to the data to write
	n	Length of the data to write, in bytes

Returns:

Actual number of bytes written

size_t ggz_tls_read	(	int	fd,
		void *	ptr,
		size_t	n
	)

Read from a secured file descriptor.

This function acts as a TLS-aware wrapper for read(2).

Parameters:

	fd	File descriptor to use
	ptr	Pointer to a buffer to store the data into
	n	Number of bytes to read, and minimum size of the buffer

Returns:

Actually read number of bytes

---