This page lists the elements of the BlackBerry Dynamics Crypto C language programming interface. More...

Functions
const char **	GDCipher_list (void)
	Return all cipher suites by name. More...

const struct GDCipher *	GDCipher_byname (const char *name)
	Return a cipher suite by name. More...

const char *	GDCipher_name (const struct GDCipherContext *ctx)
	Return a cipher suite's name. More...

const struct GDCipher *	GDCipher_bycontext (const struct GDCipherContext *ctx)
	Return a cipher by context. More...

int	GDCipher_block_size (const struct GDCipher *cipher)
	Return the cipher block size. More...

int	GDCipher_key_length (const struct GDCipher *cipher)
	Return the cipher key length. More...

int	GDCipher_iv_length (const struct GDCipher *cipher)
	Return the IV length. More...

unsigned long	GDCipher_mode (const struct GDCipher *cipher)
	Return the cipher mode. More...

void	GDCipher_set_padding (struct GDCipherContext *ctx, int padding)
	Enable or disable padding. More...

struct GDCipherContext *	GDCipher_new (void)
	Return a new cipher context. More...

int	GDCipher_init (struct GDCipherContext ctx, const struct GDCipher cipher, const void key, const void iv, int mode)
	Initialize a cipher context. More...

int	GDCipher_copy (struct GDCipherContext destination, const struct GDCipherContext source)
	Copy a cipher context. More...

int	GDCipher_update (struct GDCipherContext ctx, void out_data, int out_data_sz, const void in_data, int in_data_sz)
	Encipher or decipher. More...

int	GDCipher_final (struct GDCipherContext ctx, void out_data, int *out_sz)
	Encipher or decipher last block. More...

int	GDCipher (struct GDCipherContext ctx, void out_data, const void *in_data, unsigned int in_data_sz)
	Encipher or decipher. More...

int	GDCipher_cleanup (struct GDCipherContext *ctx)
	Clears all information from a cipher context. More...

void	GDCipher_free (struct GDCipherContext *ctx)
	Free the cipher context. More...

const struct GDDigest *	GDDigest_byname (const char *name)
	Return a digest algorithm by name. More...

const char *	GDDigest_name (const struct GDDigestContext *ctx)
	Return a digest's name. More...

const struct GDDigest *	GDDigest_bycontext (const struct GDDigestContext *ctx)
	Return a digest by context. More...

int	GDDigest_size (const struct GDDigest *digest)
	Size of a digest in bytes. More...

int	GDDigest_block_size (const struct GDDigest *digest)
	Return the digest block size. More...

struct GDDigestContext *	GDDigest_new (void)
	Return a new digest context. More...

int	GDDigest_init (struct GDDigestContext ctx, const struct GDDigest algorithm)
	Initialize a digest context. More...

int	GDDigest_copy (struct GDDigestContext destination, const struct GDDigestContext source)
	Copy a digest context. More...

int	GDDigest_update (struct GDDigestContext ctx, const void message, size_t message_sz)
	Calculate a digest. More...

int	GDDigest_final (struct GDDigestContext ctx, void digest, unsigned int *digest_sz)
	Finalize and output the digest. More...

int	GDDigest (const void data, size_t data_sz, void md, unsigned int md_sz, const struct GDDigest type)
	Calculate a digest. More...

int	GDDigest_sign_init (struct GDDigestContext ctx, struct GDKeyContext key_context, const struct GDDigest digest, struct GDKey *key)
	Initialize a digest context for signing. More...

int	GDDigest_sign_final (struct GDDigestContext ctx, void signature, size_t *signature_sz)
	Sign a digest. More...

int	GDDigest_verify_init (struct GDDigestContext ctx, struct GDKeyContext key_ctx, const struct GDDigest digest, struct GDKey *key)
	Initialize a digest context for verification. More...

int	GDDigest_verify_final (struct GDDigestContext ctx, const void signature, size_t signature_sz)
	Verify a digest. More...

int	GDDigest_cleanup (struct GDDigestContext *ctx)
	Clears all information from a digest context. More...

void	GDDigest_free (struct GDDigestContext *ctx)
	Free the digest context. More...

unsigned long	GDCryptoError_get (void)
	Retrieve the earliest error code. More...

unsigned long	GDCryptoError_peek (void)
	Read the earliest error code. More...

unsigned long	GDCryptoError_peek_last (void)
	Read the latest error code. More...

void	GDCryptoError_clear (void)
	Empties the error stack. More...

const char *	GDCryptoError_string (unsigned long e)
	Return a human-readable string representing the error code. More...

const char *	GDCryptoError_detailed_string (void)
	Return a detailed human-readable string of the last error. More...

int	GDFIPS_mode (void)
	Retrieve the current FIPS 140-2 mode of operation. More...

struct GDX509 *	GDX509_copy (const struct GDX509 *cert)
	Copy a X509 structure. More...

void	GDX509_free (struct GDX509 *cert)
	Free a X509 structure. More...

struct GDX509List *	GDX509List_read (const char *pem, int pem_length)
	Retrieve a list of X509 certificates within a PEM container. More...

struct GDX509List *	GDX509List_copy (const struct GDX509List *certs)
	Copy a list of X509 certificates. More...

int	GDX509List_num (const struct GDX509List *certs)
	Count the number of X509 certificates. More...

const struct GDX509 *	GDX509List_value (const struct GDX509List *certs, int index)
	Retrieve an X509 certificate from a list. More...

void	GDX509List_insert (const struct GDX509List certs, int index, const struct GDX509 cert)
	Insert a certificate into the list. More...

bool	GDX509List_evaluate (const struct GDX509List certs, const struct GDX509List not_used, const char hostname, char *reason)
	Evaluate a certificate chain. More...

struct GDX509List *	GDX509List_trusted_authorities (void)
	Retrieve a list of trusted X509 certificate authorities. More...

struct GDX509List *	GDX509List_all_user_certs (void)
	Retrieve all user certificates managed by Dynamics. More...

struct GDX509List *	GDX509List_valid_user_signing_certs (void)
	Retrieve all valid user certificates managed by Dynamics. More...

struct GDX509List *	GDX509List_valid_user_encryption_certs (void)
	Retrieve all valid user encryption certificates managed by Dynamics. More...

struct GDX509List *	GDX509List_all_user_encryption_certs (void)
	Retrieve all user encryption certificates managed by Dynamics. More...

struct GDX509List *	GDX509List_aux_certs (const struct GDX509 *cert)
	Retrieve a certificate chain for a user certificate. More...

void	GDX509List_free (struct GDX509List *certs)
	Free a X509 list structure. More...

struct GDKey *	GDKey_public (const struct GDX509 *cert)
	Retrieve the public key. More...

struct GDKey *	GDKey_private (const struct GDX509 *cert)
	Retrieve an opaque private key corresponding to a user certificate. More...

void	GDKey_free (struct GDKey *key)
	Free a key structure. More...

int	GDKey_compare (const struct GDKey a, const struct GDKey b)
	Compare two keys. More...

int	GDKey_size (const struct GDKey *key)
	Signature size. More...

int	GDKey_bits (const struct GDKey *key)
	Key size. More...

int	GDKey_type (const struct GDKey *key)
	Key type. More...

const char *	GDKey_name (const struct GDKey *key)
	Return the key algorithm name. More...

struct GDKeyContext *	GDKeyContext_new (struct GDKey *key)
	Create a new key context. More...

struct GDKeyContext *	GDKeyContext_copy (struct GDKeyContext *ctx)
	Copy a key context. More...

void	GDKeyContext_free (struct GDKeyContext *ctx)
	Free a key context. More...

int	GDKey_sign_init (struct GDKeyContext *ctx)
	Initialize a key context for signing. More...

int	GDKey_sign (struct GDKeyContext ctx, void signature, size_t signature_length, const void message, size_t message_length)
	Sign a message. More...

int	GDKey_verify_init (struct GDKeyContext *ctx)
	Initialize a key context for verification. More...

int	GDKey_verify (struct GDKeyContext ctx, const void signature, size_t signature_length, const void *message, size_t message_length)
	Verify a signed message. More...

int	GDKey_encrypt_init (struct GDKeyContext *ctx)
	Initialize a key context for encryption. More...

int	GDKey_encrypt (struct GDKeyContext ctx, void encrypted, size_t encrypted_length, const void clear, size_t clear_length)
	Encrypt data. More...

int	GDKey_decrypt_init (struct GDKeyContext *ctx)
	Initialize a key context for decryption. More...

int	GDKey_decrypt (struct GDKeyContext ctx, void clear, size_t clear_length, const void encrypted, size_t encrypted_length)
	Decrypt data. More...

int	GDKey_sign_final (struct GDDigestContext digest, void signature, unsigned int signature_length, struct GDKey key)
	Sign a digest. More...

int	GDKey_verify_final (struct GDDigestContext digest, const void signature, unsigned int signature_length, struct GDKey *key)
	Verify a digest. More...

int	GDKey_set_signature_md (struct GDKeyContext ctx, const struct GDDigest digest)
	Sets the message digest type used in a signature. More...

int	GDKey_get_signature_md (struct GDKeyContext ctx, const struct GDDigest *digest)
	Returns the message digest type. More...

struct GDPKCS7 *	GDPKCS7_SMIME_read (struct GDStream stream, struct GDStream *clearText, int flags)
	Deserialize SMIME to a PKCS7 structure. More...

struct GDPKCS7 *	GDPKCS7_read (struct GDStream *stream, int flags)
	Deserialize ASN.1/DER encoding to a PKCS7 structure. More...

int	GDPKCS7_type (struct GDPKCS7 *p7, int flags)
	Retrieve the type of PKCS7 structure. More...

int	GDPKCS7_verify (struct GDPKCS7 p7, const struct GDX509List certs, const struct GDX509List anchors, struct GDStream indata, struct GDStream *out, int flags)
	Verify a PKCS7 signedData structure. More...

const struct GDX509List *	GDPKCS7_get_signers (struct GDPKCS7 *p7, int flags)
	Retrieve the signer's certificate(s). More...

int	GDPKCS7_decrypt (struct GDPKCS7 p7, struct GDKey pkey, const struct GDX509 cert, struct GDStream data, int flags)
	Decrypt a PKCS7 envelopedData structure. More...

struct GDPKCS7 *	GDPKCS7_encrypt (struct GDX509List certs, struct GDStream in, const struct GDCipher *cipher, int flags)
	Create a PKCS7 envelopedData structure. More...

struct GDPKCS7 *	GDPKCS7_add_signer (const struct GDX509 signcert, struct GDKey pkey, struct GDX509List certs, const struct GDDigest md, int flags)
	Add signer information to a PKCS7 structure. More...

int	GDPKCS7_final (struct GDPKCS7 p7, struct GDStream data, int flags)
	Finalize a PKCS7 structure. More...

int	GDPKCS7_write (struct GDStream stream, struct GDPKCS7 p7, int flags)
	Serialize a PKCS7 structure to ASN.1/DER encoding. More...

int	GDPKCS7_SMIME_write (struct GDStream stream, struct GDPKCS7 p7, struct GDStream *data, int flags)
	Serialize a PKCS7 structure to SMIME encoding. More...

void	GDPKCS7_free (struct GDPKCS7 *p7, int flags)
	Free a PKCS7 structure. More...

const struct GDStreamStorageMethod *	GDStream_mem_storage_method (void)
	Retrieve a memory stream storage method. More...

struct GDStream *	GDStream_new_mem_buf (const void *buf, int len)
	Create a stream from a region of memory. More...

struct GDStream *	GDStream_new (const struct GDStreamStorageMethod *method)
	Create a stream. More...

int	GDStream_read (struct GDStream stream, void data, int len)
	Read from a stream. More...

int	GDStream_write (struct GDStream stream, const void data, int len)
	Write to a stream. More...

int	GDStream_reset (struct GDStream *stream)
	Reset a stream. More...

int	GDStream_eof (struct GDStream *stream)
	Tells if stream has reached the end. More...

void	GDStream_free (struct GDStream *stream)
	Free a stream structure. More...

Variables
const int	GDCIPHER_MAX_BLOCK_LENGTH
	Maximum block length for all ciphers. More...

const int	GDCIPHER_MAX_KEY_LENGTH
	Maximum key length for all ciphers. More...

const unsigned long	GDCIPHER_STREAM_CIPHER
	Stream cipher mode.

const unsigned long	GDCIPHER_ECB_MODE
	ECB cipher mode.

const unsigned long	GDCIPHER_CBC_MODE
	CBC cipher mode.

const unsigned long	GDCIPHER_CFB_MODE
	CFB cipher mode.

const unsigned long	GDCIPHER_OFB_MODE
	OFB cipher mode.

const unsigned long	GDCIPHER_CTR_MODE
	CTR cipher mode.

const unsigned long	GDCIPHER_GCM_MODE
	GCM cipher mode.

const unsigned long	GDCIPHER_CCM_MODE
	CCM cipher mode.

const unsigned long	GDCIPHER_XTS_MODE
	XTS cipher mode.

const unsigned long	GDCIPHER_WRAP_MODE
	Wrap cipher mode.

const int	GDDIGEST_MAX_SIZE
	Maximum supported digest size in bytes. More...

const int	GDKEY_TYPE_RSA
	RSA key type. More...

const int	GDKEY_TYPE_DSA
	DSA key type. More...

const int	GDKEY_TYPE_EC
	EC key type. More...

const int	GDPKCS7_TEXT
	PKCS7 flags. More...

const int	GDPKCS7_SIGNED
	PKCS7 content-type:pkcs7-signedData. More...

const int	GDPKCS7_ENCRYPTED
	PKCS7 content-type:pkcs7-encryptedData. More...

const int	GDPKCS7_ENVELOPED
	PKCS7 content-type:pkcs7-envelopedData. More...

const int	GDPKCS7_SIGNED_AND_ENVELOPED
	PKCS7 content-type:pkcs7-signedAndEnvelopedData. More...

const int	GDPKCS7_DATA
	PKCS7 content-type:pkcs7-data. More...

const int	GDPKCS7_DIGEST
	PKCS7 content-type:pkcs7-digestData. More...

Detailed Description

This is a C language programming interface for performing cryptographic operations. The interface enables an app to perform PKCS7 sign, verify, encrypt, decrypt operations.

It can be used by applications built with the Android Native Development Kit (NDK).

Function Documentation

◆ GDCipher_list()

const char** GDCipher_list ( void )

Returns an array of supported cipher suite names.

Returns: char** an array of c-strings containing the cipher names.

◆ GDCipher_byname()

const struct GDCipher* GDCipher_byname ( const char * name )

Returns a cipher structure by suite name. The name must be the long name format as specified in obj_mac.h of OpenSSL.

Parameters

name	`char*` the name of the cipher suite required. For example, "des-ede3-cbc".

Returns: GDCipher* the cipher suite or NULL. If NULL, the reason can be obtained from GDCryptoError_get().

◆ GDCipher_name()

const char* GDCipher_name ( const struct GDCipherContext * ctx )

Returns the name of the given cipher suite. The name will be in long name format as specified in obj_mac.h of OpenSSL.

Parameters

ctx	`GDCipherContext*` the cipher context for which the name is required.

Returns: char* the cipher suite name or NULL.

◆ GDCipher_bycontext()

const struct GDCipher* GDCipher_bycontext ( const struct GDCipherContext * ctx )

Returns a cipher structure for the given cipher context.

Parameters

ctx	`GDCipherContext*` the context of the cipher required.

Returns: GDCipher* the cipher suite or NULL.

◆ GDCipher_block_size()

int GDCipher_block_size ( const struct GDCipher * cipher )

Returns the block size of a given cipher.

Parameters

cipher GDCipher* the cipher for which the block size is required.

Returns: int the block size of the cipher in bytes.

◆ GDCipher_key_length()

int GDCipher_key_length ( const struct GDCipher * cipher )

Returns the key length of a given cipher.

Parameters

cipher GDCipher* the cipher for which the key length is required.

Returns: int the key length of the cipher.

◆ GDCipher_iv_length()

int GDCipher_iv_length ( const struct GDCipher * cipher )

Returns the IV length of a given cipher.

Parameters

cipher GDCipher* the cipher for which the IV length is required.

Returns: int the IV length of the cipher.

◆ GDCipher_mode()

unsigned long GDCipher_mode ( const struct GDCipher * cipher )

Returns the mode of a given cipher.

Parameters

cipher GDCipher* the cipher for which the mode is required.

Returns: unsigned long the mode of the cipher.

◆ GDCipher_set_padding()

void GDCipher_set_padding	(	struct GDCipherContext *	ctx,
		int	padding
	)

Enable or disable padding for the given cipher context.

Parameters

ctx	`GDCipherContext*` the cipher context for which padding is to be enabled or disabled.
padding	`int` 0 for no padding, any other value to enable padding.

◆ GDCipher_new()

struct GDCipherContext* GDCipher_new ( void )

A cipher context is used to symmetrically encrypt or decrypt a message. The context should be initialized with a specific cipher algorithm by calling GDCipher_init().

Returns: GDCipherContext* a cipher context.

◆ GDCipher_init()

int GDCipher_init	(	struct GDCipherContext *	ctx,
		const struct GDCipher *	cipher,
		const void *	key,
		const void *	iv,
		int	mode
	)

Initialize the cipher context with a specific cipher suite.

Parameters

ctx	`GDCipherContext*` a pointer to the cipher context.
cipher	`const GDCipher*` the cipher suite, for example AES-256-CBC.
key	`const void*` NULL or the symmetric key to use, depending on the cipher.
iv	`const void*` NULL or the IV to use, depending on the cipher.
mode	`int` 1 for encryption, 0 for decryption

Returns: int 1 for success, 0 for failure.

◆ GDCipher_copy()

int GDCipher_copy	(	struct GDCipherContext *	destination,
		const struct GDCipherContext *	source
	)

Copies the cipher context. The destination cipher is cleaned up before being updated to match the source cipher.

Parameters

source	`GDCipherContext*` a pointer to a cipher context.
destination	`const GDCipherContext*` the cipher context to copy.

Returns: int 1 for success, 0 for failure.

◆ GDCipher_update()

int GDCipher_update	(	struct GDCipherContext *	ctx,
		void *	out_data,
		int *	out_data_sz,
		const void *	in_data,
		int	in_data_sz
	)

Perform encryption or decryption of a message. This function can be called multiple times to encrypt or decrypt successive blocks of data.

Parameters

ctx	`GDCipherContext*` a pointer to the cipher context.
out_data	`void*` a buffer large enough to contain the encrypted or decrypted data. The amount of data written may be anything from zero bytes to (in_sz + cipher_block_size - 1).
out_data_sz	`size_t` the number of bytes written to out_data.
in_data	`const void*` a pointer to the data to be encrypted or decrypted.
in_data_sz	`int` the number of bytes of the data to be encrypted.

Returns: int 1 for success, 0 for failure.

◆ GDCipher_final()

int GDCipher_final	(	struct GDCipherContext *	ctx,
		void *	out_data,
		int *	out_sz
	)

Finish encryption or decryption of the last block of data.

Parameters

ctx	`GDCipherContext*` a pointer to the cipher context.
out_data	`size_t` a buffer large enough to contain the encrypted or decrypted data. The amount of data written may be anything from zero bytes to (remaining_sz + cipher_block_size - 1).
out_sz	`size_t` the number of bytes written to out_data.

Returns: int 1 for success, 0 for failure.

◆ GDCipher()

int GDCipher	(	struct GDCipherContext *	ctx,
		void *	out_data,
		const void *	in_data,
		unsigned int	in_data_sz
	)

Perform encryption or decryption of a message.

Parameters

ctx	`GDCipherContext*` a pointer to the cipher context.
out_data	`void*` a buffer large enough to contain the encrypted or decrypted data. The amount of data written may be anything from zero bytes to (in_sz + cipher_block_size - 1).
in_data	`const void*` a pointer to the data to be encrypted or decrypted.
in_data_sz	`unsigned int` the number of bytes of the data to be encrypted.

Returns: int 1 for success, 0 for failure.

◆ GDCipher_cleanup()

int GDCipher_cleanup ( struct GDCipherContext * ctx )

Clears all information from a cipher context and frees up any allocated memory associate with it. It should be called after all operations using a cipher are complete so sensitive information does not remain in memory.

Parameters

ctx	`GDCipherContext*` a pointer to the cipher context.

Returns: int 1 for success, 0 for failure.

◆ GDCipher_free()

void GDCipher_free ( struct GDCipherContext * ctx )

Deallocate cipher context resources. It does not free the buffer holding the encrypted or decrypted data that the caller supplied to GDCipher_final().

Parameters

ctx	`GDCipherContext*` a pointer to the cipher context to free.

◆ GDDigest_byname()

const struct GDDigest* GDDigest_byname ( const char * name )

Returns a digest algorithm structure by name. The name must be the long name format as specified in obj_mac.h of OpenSSL.

Parameters

name	`char*` the name of the digest required. For example, "sha256".

Returns: int the digest or NULL. If NULL, the reason can be obtained from GDCryptoError_get().

◆ GDDigest_name()

const char* GDDigest_name ( const struct GDDigestContext * ctx )

Returns the name of the given digest structure. The name will be in long name format as specified in obj_mac.h of OpenSSL.

Parameters

ctx	`GDDigestContext*` the digest context for which the name is required.

Returns: char* the digest name or NULL.

◆ GDDigest_bycontext()

const struct GDDigest* GDDigest_bycontext ( const struct GDDigestContext * ctx )

Returns a digest structure for the given digest context.

Parameters

ctx	`GDDigestContext*` the context of the digest required.

Returns: GDDigest* the digest or NULL. If NULL, the reason can be obtained from GDCryptoError_get().

◆ GDDigest_size()

int GDDigest_size ( const struct GDDigest * digest )

Returns the specified digest size in bytes.

Parameters

digest const GDDigest* digest the digest. For example, "sha256".

Returns: int the digest size.

◆ GDDigest_block_size()

int GDDigest_block_size ( const struct GDDigest * digest )

Returns the block size of a given digest.

Parameters

digest GDCipher* the digest for which the block size is required.

Returns: int the block size of the digest in bytes.

◆ GDDigest_new()

struct GDDigestContext* GDDigest_new ( void )

A digest context is used to calculate the digest (hash) of a message. The context should be initialized with a specific digest algorithm by calling GDDigest_init().

Returns: GDDigestContext* a digest context.

◆ GDDigest_init()

int GDDigest_init	(	struct GDDigestContext *	ctx,
		const struct GDDigest *	algorithm
	)

Initialize the digest context with a specific digest algorithm.

Parameters

ctx	`GDDigestContext*` a pointer to the digest context.
algorithm	`const GDDigest*` the digest algorithm, for example SHA-256.

Returns: int 1 for success, 0 for failure.

◆ GDDigest_copy()

int GDDigest_copy	(	struct GDDigestContext *	destination,
		const struct GDDigestContext *	source
	)

Copies the digest context. The destination digest is cleaned up before being updated to match the source digest.

Parameters

source	`GDDigestContext*` a pointer to a digest context.
destination	`const GDDigestContext*` the digest context to copy.

Returns: int 1 for success, 0 for failure.

◆ GDDigest_update()

int GDDigest_update	(	struct GDDigestContext *	ctx,
		const void *	message,
		size_t	message_sz
	)

Calculate the digest of a message. This function can be called multiple times to update the digest with additional message data.

Parameters

ctx	`GDDigestContext*` a pointer to the digest context.
message	`const void*` a pointer to the message chunk.
message_sz	`size_t` the number of bytes of the message chunk.

Returns: int 1 for success, 0 for failure.

◆ GDDigest_final()

int GDDigest_final	(	struct GDDigestContext *	ctx,
		void *	digest,
		unsigned int *	digest_sz
	)

Return the final digest of the complete message.

Parameters

ctx	`GDDigestContext*` a pointer to the digest context.
digest	`void*` a pointer to memory large enough to contain the digest. The caller must allocate and eventually free this buffer. The size of the buffer required can be determined by calling GDDigest_size(), or using GDDIGEST_MAX_SIZE.
digest_sz	`size_t` the number of digest bytes copied to digest.

Returns: int 1 for success, 0 for failure.

◆ GDDigest()

int GDDigest	(	const void *	data,
		size_t	data_sz,
		void *	md,
		unsigned int *	md_sz,
		const struct GDDigest *	type
	)

Calculate the digest of a message.

Parameters

data	`const void*` a buffer containing the data to hash.
data_sz	`size_t` the size of the buffer containing the data to hash.
md	`void*` a buffer large enough to contain the digest.
md_sz	`size_t` upon return, the number of bytes of the calculated digest.
type	`GDDigest*` the digest required.

Returns: int 1 for success, 0 for failure.

◆ GDDigest_sign_init()

int GDDigest_sign_init	(	struct GDDigestContext *	ctx,
		struct GDKeyContext **	key_context,
		const struct GDDigest *	digest,
		struct GDKey *	key
	)

Initialize a digest context for a signing operation.

Parameters

ctx	`GDDigestContext*` the digest context to initialize.
key_context	`GDKeyContext**` if not NULL, upon return, a key context that can be used to set additional signing parameters. The key context will be freed automatically when the digest context is freed.
digest	`GDDigest*` the digest algorithm to use when signing.
key	`GDKey*` the signer's private key.

Returns: int 1 for success, 0 or a negative value for failure.

◆ GDDigest_sign_final()

int GDDigest_sign_final	(	struct GDDigestContext *	ctx,
		void *	signature,
		size_t *	signature_sz
	)

Signs a message digest.

Parameters

ctx	`GDDigestContext*` the initialized digest context to use when signing.
signature	`void*` a buffer large enough to contain the signature. If NULL, the size required is returned in signature_sz.
signature_sz	`GDDigest*` upon return, the size of the signature.

Returns: int 1 for success and 0 or a negative value for failure.

◆ GDDigest_verify_init()

int GDDigest_verify_init	(	struct GDDigestContext *	ctx,
		struct GDKeyContext **	key_ctx,
		const struct GDDigest *	digest,
		struct GDKey *	key
	)

Initialize a digest context for a verification operation.

Parameters

ctx	`GDDigestContext*` the digest context to initialize.
key_ctx	`GDKeyContext**` if not NULL, upon return, a key context that can be used to set additional verification parameters. The key context will be freed automatically when the digest context is freed.
digest	`GDDigest*` the digest algorithm to use when verifying.
key	`GDKey*` the signer's public key.

Returns: int 1 for success, 0 for failure.

◆ GDDigest_verify_final()

int GDDigest_verify_final	(	struct GDDigestContext *	ctx,
		const void *	signature,
		size_t	signature_sz
	)

Verifies a message digest.

Parameters

ctx	`GDDigestContext*` the initialized digest context to use for verification.
signature	`void*` a buffer containing a signature.
signature_sz	`GDDigest*` the size of the signature buffer.

Returns: 1 for successful verification, 0 for verification failure (not an error - message or signature is not to be trusted), or a negative value for a more serious error. The reason for failure can be obtained from GDCryptoError_get().

◆ GDDigest_cleanup()

int GDDigest_cleanup ( struct GDDigestContext * ctx )

Clears all information from a digest context and frees up any allocated memory associate with it. It should be called after all operations using a digest are complete so sensitive information does not remain in memory.

Parameters

ctx	`GDDigestContext*` a pointer to the digest context.

Returns: int 1 for success, 0 for failure.

◆ GDDigest_free()

void GDDigest_free ( struct GDDigestContext * ctx )

Deallocate digest context resources. It does not free the digest buffer that the caller supplied to GDDigest_final().

Parameters

ctx	`GDDigestContext*` a pointer to the digest context to free.

◆ GDCryptoError_get()

unsigned long GDCryptoError_get ( void )

Returns the earliest error code from the thread's error stack and removes the entry. This function can be called repeatedly until there are no more error codes to return.

Returns: unsigned long an error code, or 0 if there is no error in the queue.

◆ GDCryptoError_peek()

unsigned long GDCryptoError_peek ( void )

Returns the earliest error code without modifying the error stack for this thread.

Returns: unsigned long The error code, or 0 if there is no error in the queue.

◆ GDCryptoError_peek_last()

unsigned long GDCryptoError_peek_last ( void )

Returns the latest error code without modifying the error stack for this thread.

Returns: unsigned long The error code, or 0 if there is no error in the queue.

◆ GDCryptoError_clear()

void GDCryptoError_clear ( void )

Clear the thread's error stack.

◆ GDCryptoError_string()

const char* GDCryptoError_string ( unsigned long e )

Generates a human-readable string representing the error code.

Parameters

e	`unsigned long` the error code.

Returns: char* a pointer to a static buffer containing the string.

◆ GDCryptoError_detailed_string()

const char* GDCryptoError_detailed_string ( void )

Generates a human-readable string with additional technical information if avaiable.

Returns: char* a pointer to a static buffer containing the string.

◆ GDFIPS_mode()

int GDFIPS_mode ( void )

This function returns the FIPS mode of operation. When in FIPS mode, calls to the Dynamics Crypto API will fail if an algorithm not compliant with FIPS 140-2 is used.

Returns: int A return code of non-zero indicates FIPS mode, 0 indicates non-FIPS mode.

◆ GDX509_copy()

struct GDX509* GDX509_copy ( const struct GDX509 * cert )

Copy resources held by the X509 structure.

Parameters

cert	`GDX509*` the X509 structure to copy.

◆ GDX509_free()

void GDX509_free ( struct GDX509 * cert )

Deallocates resources held by the X509 structure.

Parameters

cert	`GDX509*` the X509 structure to free.

◆ GDX509List_read()

struct GDX509List* GDX509List_read	(	const char *	pem,
		int	pem_length
	)

Decodes a PEM container and returns a list of certificates within.

Parameters

pem	`const char*` a pointer to the PEM data.
pem_length	`int` length of the PEM data.

Returns: GDX509List* the list of certificates within the PEM data. If NULL, the reason can be obtained from GDCryptoError_get().

◆ GDX509List_copy()

struct GDX509List* GDX509List_copy ( const struct GDX509List * certs )

Copies and returns a list of certificates.

Parameters

certs GDX509List* the list to copy.

Returns: GDX509List* the copied list of certificates. If NULL, the reason can be obtained from GDCryptoError_get().

◆ GDX509List_num()

int GDX509List_num ( const struct GDX509List * certs )

Returns the number of X509 certificates within a list.

Parameters

certs GDX509List* the list of certificates to count.

Returns: int the number of certificates within the list.

◆ GDX509List_value()

const struct GDX509* GDX509List_value	(	const struct GDX509List *	certs,
		int	index
	)

Returns an X509 certificate at a zero-based index within the list.

Parameters

certs	`GDX509List*` the list of certificates to access.
index	`int` the index of list to access.

Returns: GDX509* the certificate at the specified index.

◆ GDX509List_insert()

void GDX509List_insert	(	const struct GDX509List *	certs,
		int	index,
		const struct GDX509 *	cert
	)

Copies and inserts a X509 certificate into a list at a given index.

Parameters

certs	`GDX509List*` the list of certificates to insert into.
index	`int` the index within the list to insert the certificate.
cert	`GDX509*` the certificate to copy and insert.

◆ GDX509List_evaluate()

bool GDX509List_evaluate	(	const struct GDX509List *	certs,
		const struct GDX509List *	not_used,
		const char *	hostname,
		char **	reason
	)

Evaluates whether the certificate can be trusted. A certificate is trustworthy if an unbroken chain of trust back to the root Certificate Authority (CA) within the trust store can be established. Validity periods and signatures of the leaf certificate and intermediates (if any) are checked.

The Dynamics trust store will be searched first, and if the device certificate store is enabled it may also be used during evaluation.

Parameters

certs	`GDX509List*` the certificate to evaluate, followed by intermediates (if any).
not_used	`GDX509List*` must be NULL.
hostname	`char*` the name of the server if used to evaluate a TLS server certificate.
reason	`char**` allocated and set to the reason for failure upon return, NULL otherwise. The caller is responsible for deallocating by calling free.

Returns: bool true if the certificate chain is trusted, false otherwise.

◆ GDX509List_trusted_authorities()

struct GDX509List* GDX509List_trusted_authorities ( void )

Returns a list of trusted certificate authorities found within the Dynamics container.

Returns: GDX509List* a list of trusted certificate authorities or NULL if not found.

◆ GDX509List_all_user_certs()

struct GDX509List* GDX509List_all_user_certs ( void )

Return a list of user certificates known to Dynamics.

Returns: GDX509List* a list of all user certificates known to Dynamics, NULL if none.

◆ GDX509List_valid_user_signing_certs()

struct GDX509List* GDX509List_valid_user_signing_certs ( void )

Return a list of user certificates known to Dynamics if the device's time falls within the certificate's validity date range.

Returns: GDX509List* a list of all valid user certificates known to Dynamics, NULL if none.

◆ GDX509List_valid_user_encryption_certs()

struct GDX509List* GDX509List_valid_user_encryption_certs ( void )

Return a list of user certificates known to Dynamics if the device's time falls within the certificate's validity date range, and usage properties permit it to be used for encryption purposes.

Returns: GDX509List* a list of all valid user encryption certificates known to Dynamics, NULL if none.

◆ GDX509List_all_user_encryption_certs()

struct GDX509List* GDX509List_all_user_encryption_certs ( void )

Return a list of user certificates known to Dynamics if usage properties permit it to be used for encryption purposes. The list may include expired certificates.

Returns: GDX509List* a list of all user encryption certificates known to Dynamics, NULL if none.

◆ GDX509List_aux_certs()

struct GDX509List* GDX509List_aux_certs ( const struct GDX509 * cert )

Return a certificate chain for the user certificate, containing intermediate certificates, if any.

Parameters

cert	`GDX509*` the user certificates for which the chain is required.

Returns: GDX509List* a list of intermediate certificates or NULL if none.

◆ GDX509List_free()

void GDX509List_free ( struct GDX509List * certs )

Deallocates resources held by the X509 list structure.

Parameters

certs GDX509List* the X509 list structure to free.

◆ GDKey_public()

struct GDKey* GDKey_public ( const struct GDX509 * cert )

Return the public key from within the supplied certificate.

Parameters

cert	`GDX509*` the certificate for which the key is required.

Returns: GDKey* the public key of the certificate. If NULL, the reason can be obtained from GDCryptoError_get().

◆ GDKey_private()

struct GDKey* GDKey_private ( const struct GDX509 * cert )

Return the private key corresponding to a user certificate stored within the Dynamics Key Store. The key data is not meaningful and will yield garbage if used to sign or decrypt data using external (non-Dynamics) APIs.

Parameters

cert	`GDX509*` the certificate for which the private key is required.

Returns: GDKey* the private key of the certificate. If NULL, the reason can be obtained from GDCryptoError_get().

◆ GDKey_free()

void GDKey_free ( struct GDKey * key )

Deallocates resources held by the key structure.

Parameters

key	`GDKey*` the key structure to free.

◆ GDKey_compare()

int GDKey_compare	(	const struct GDKey *	a,
		const struct GDKey *	b
	)

Compare two keys.

Parameters

a	`GDKey*` key a.
b	`GDKey*` key b.

Returns: int 1 if the keys match, 0 if they don't match, -1 if the key types are different and -2 if the operation is not supported.

◆ GDKey_size()

int GDKey_size ( const struct GDKey * key )

Returns the maximum size of an ASN.1 encoded signature in bytes. It can be used to determine how much memory must be allocated for a signature.

Parameters

key	`GDKey*` the key for which the signature size is required.

Returns: int the maximum signature size in bytes.

◆ GDKey_bits()

int GDKey_bits ( const struct GDKey * key )

Returns the key size in bits.

Parameters

key	`GDKey*` the key for which the size is required.

Returns: int the key size in bits.

◆ GDKey_type()

int GDKey_type ( const struct GDKey * key )

Returns the type of the underlying key.

Parameters

key	`GDKey*` the key for which the type is required.

Returns: int the key type, which will be either GDKEY_TYPE_RSA, GDKEY_TYPE_DSA, or GDKEY_TYPE_EC.

◆ GDKey_name()

const char* GDKey_name ( const struct GDKey * key )

Return the key algorithm name.

Parameters

key	`GDKey*` the key for which the algorithm name is required.

Returns: char* the key algorithm name.

◆ GDKeyContext_new()

struct GDKeyContext* GDKeyContext_new ( struct GDKey * key )

Create a new key context object. Contexts are opaque structures used by other APIs and must not be used simultaneously by multiple threads.

Parameters

key	`GDKey*` the key for which the context is required.

Returns: GDKeyContext* the key context or NULL if an error occurred.

◆ GDKeyContext_copy()

struct GDKeyContext* GDKeyContext_copy ( struct GDKeyContext * ctx )

Copy a key context object.

Parameters

ctx	`GDKey*` the source key context to copy.

Returns: GDKeyContext* a copy of the key context.

◆ GDKeyContext_free()

void GDKeyContext_free ( struct GDKeyContext * ctx )

Deallocates resources held by the key context.

Parameters

ctx	`GDKeyContext*` the key context to free.

◆ GDKey_sign_init()

int GDKey_sign_init ( struct GDKeyContext * ctx )

Initializes a key context object for a signing operation.

Parameters

ctx	`GDKeyContext*` the key context to initialize.

Returns: 1 for success and 0 or a negative value for failure. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_sign()

int GDKey_sign	(	struct GDKeyContext *	ctx,
		void *	signature,
		size_t *	signature_length,
		const void *	message,
		size_t	message_length
	)

Signs a message, usually a message digest and returns the ASN.1 DER encoded signature. This function does not calculate the digest of the data to be signed. The required size for the signature buffer can be computed by calling this function with a NULL signature buffer.

Parameters

ctx	`GDKeyContext*` the key context to sign with.
signature	`void*` NULL, or a buffer large enough to hold the signature.
signature_length	`size_t*` must be set to the length of the signature buffer, and upon return will be set to the amount of data written to the signature buffer. If signature is NULL, it will be set to the maximum size of the signature.
message	`void*` the message to sign, usually a digest.
message_length	`size_t*` the length of the message to sign.

Returns: 1 for success and 0 or a negative value for failure. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_verify_init()

int GDKey_verify_init ( struct GDKeyContext * ctx )

Initializes a key context object for a verification operation.

Parameters

ctx	`GDKeyContext*` the key context to initialize.

Returns: 1 for success and 0 or a negative value for failure. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_verify()

int GDKey_verify	(	struct GDKeyContext *	ctx,
		const void *	signature,
		size_t	signature_length,
		const void *	message,
		size_t	message_length
	)

Verifys an ASN.1 DER encoded signature.

Parameters

ctx	`GDKeyContext*` the key context to verify with.
signature	`void*` a buffer holding the signature.
signature_length	`size_t*` the length of the signature.
message	`void*` a buffer holding the message or digest to be verified.
message_length	`size_t*` the length of the message or digest to verify.

Returns: 1 for successful verification, 0 for verification failure (not an error - message or signature is not to be trusted), or a negative value for a more serious error. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_encrypt_init()

int GDKey_encrypt_init ( struct GDKeyContext * ctx )

Initializes a key context object for an encryption operation.

Parameters

ctx	`GDKeyContext*` the key context to initialize.

Returns: 1 for success and 0 or a negative value for failure. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_encrypt()

int GDKey_encrypt	(	struct GDKeyContext *	ctx,
		void *	encrypted,
		size_t *	encrypted_length,
		const void *	clear,
		size_t	clear_length
	)

Encrypts data using the key associated with the supplied key context.

Parameters

ctx	`GDKeyContext*` the key context to encrypt with.
encrypted	`void*` a buffer large enough to hold the encrypted data. If NULL, the length required is returned in encrypted_length.
encrypted_length	`size_t*` the length of the buffer supplied to hold the encrypted data, and upon successful return the actual length of the encrypted data.
clear	`void*` the data to encrypt.
clear_length	`size_t*` the length of the data to encrypt.

Returns: 1 for success, 0 or a negative value for failure. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_decrypt_init()

int GDKey_decrypt_init ( struct GDKeyContext * ctx )

Initializes a key context object for a decryption operation.

Parameters

ctx	`GDKeyContext*` the key context to initialize.

Returns: 1 for success and 0 or a negative value for failure. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_decrypt()

int GDKey_decrypt	(	struct GDKeyContext *	ctx,
		void *	clear,
		size_t *	clear_length,
		const void *	encrypted,
		size_t	encrypted_length
	)

Decrypts data using the key associated with the supplied key context.

Parameters

ctx	`GDKeyContext*` the key context to decrypt with.
clear	`void*` a buffer large enough to hold the decrypted data. If NULL, the length required is returned in clear_length.
clear_length	`size_t*` the length of the buffer supplied to hold the decrypted data, and upon successful return the actual length of the decrypted data.
encrypted	`void*` the data to decrypt.
encrypted_length	`size_t*` the length of the data to decrypt.

Returns: 1 for success, 0 or a negative value for failure. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_sign_final()

int GDKey_sign_final	(	struct GDDigestContext *	digest,
		void *	signature,
		unsigned int *	signature_length,
		struct GDKey *	key
	)

Signs a message digest. The output signature buffer size can be computed by calling GDKey_size().

Parameters

digest	`GDDigestContext*` the initialized digest context.
signature	`void*` a buffer large enough to hold the signature at least GDKey_size(key) bytes.
signature_length	`unsigned int*` upon successful return will be set to the amount of data written to the signature buffer.
key	`GDKey*` the private signing key.

Returns: 1 for success and 0 for failure. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_verify_final()

int GDKey_verify_final	(	struct GDDigestContext *	digest,
		const void *	signature,
		unsigned int	signature_length,
		struct GDKey *	key
	)

Verifies a message digest.

Parameters

digest	`GDDigestContext*` the initialized digest context to verify.
signature	`void*` a buffer containing the DER encoded signature.
signature_length	`unsigned int` the length of the signature buffer in bytes.
key	`GDKey*` the signer's public key.

Returns: 1 for successful verification, 0 for verification failure (not an error - message or signature is not to be trusted), or a negative value for a more serious error. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_set_signature_md()

int GDKey_set_signature_md	(	struct GDKeyContext *	ctx,
		const struct GDDigest *	digest
	)

Sets the digest algorithm to be used when calculating a signature.

Parameters

ctx	`GDKeyContext*` the key context to setup.
digest	`GDDigest*` the digest algorithm to use.

Returns: 1 for success, 0 for failure. The reason for failure can be obtained from GDCryptoError_get().

◆ GDKey_get_signature_md()

int GDKey_get_signature_md	(	struct GDKeyContext *	ctx,
		const struct GDDigest **	digest
	)

Returns the digest algorithm for a given key context.

Parameters

ctx	`GDKeyContext*` the key context to query.
digest	`GDDigest**` the digest algorithm returned.

Returns: 1 for success, 0 for failure. The reason for failure can be obtained from GDCryptoError_get().

◆ GDPKCS7_SMIME_read()

struct GDPKCS7* GDPKCS7_SMIME_read	(	struct GDStream *	stream,
		struct GDStream **	clearText,
		int	flags
	)

Deserialize SMIME content received over a network, read from a file, and so on.

Parameters

stream	`GDStream*` the stream to read the SMIME message from.
clearText	`GDStream*` if cleartext signing is used then the content is returned in a memory stream, otherwise clearText is set to NULL. The caller is responsible for freeing the stream.
flags	`int` optional set of flags.

Returns: GDPKCS7* a PKCS7 structure or NULL if an error occurred. The error can be obtained from GDCryptoError_get().

◆ GDPKCS7_read()

struct GDPKCS7* GDPKCS7_read	(	struct GDStream *	stream,
		int	flags
	)

Deserialize ASN.1/DER encoded PKCS7 content received over a network, read from a file, and so on.

Parameters

stream	`GDStream*` the stream to read the ASN.1/DER encoded data from.
flags	`int` optional set of flags.

Returns: GDPKCS7* a PKCS7 structure or NULL if an error occurred. The error can be obtained from GDCryptoError_get().

◆ GDPKCS7_type()

int GDPKCS7_type	(	struct GDPKCS7 *	p7,
		int	flags
	)

Retrieve the type of the PKCS7 structure.

Parameters

p7	`GDPKCS7*` the PKCS7 structure to verify. The PKCS7 structure may be obtained from an initial call to GDPKCS7_read(), GDPKCS7_encrypt(), or GDPKCS7_add_signer().
flags	`int` optional set of flags.

Returns: int the type of the PKCS7 structure.

◆ GDPKCS7_verify()

int GDPKCS7_verify	(	struct GDPKCS7 *	p7,
		const struct GDX509List *	certs,
		const struct GDX509List *	anchors,
		struct GDStream *	indata,
		struct GDStream *	out,
		int	flags
	)

Verifies a PKCS7 signedData structure.

Parameters

p7	`GDPKCS7*` the PKCS7 structure to verify. The PKCS7 structure may be obtained from an initial call to GDPKCS7_read().
certs	`GDX509List*` a set of certificates in which to search for the signer's certificate.
anchors	`GDX509List*` an optional set of trusted certificate authorities or NULL if using the Dynamics trusted certificate store.
indata	`GDStream*` the signed data if the content is detached.
out	`GDStream*` the content is written to out if it is not NULL.
flags	`int` optional set of flags.

Returns: int 1 for a successful verification and 0 if an error occurs. The error can be obtained from GDCryptoError_get().

◆ GDPKCS7_get_signers()

const struct GDX509List* GDPKCS7_get_signers	(	struct GDPKCS7 *	p7,
		int	flags
	)

Retrieve the signer's certificate(s) from a PKCS7 signedData structure.

Parameters

p7	`GDPKCS7*` the PKCS7 signedData. The PKCS7 structure may be obtained from an initial call to GDPKCS7_read().
flags	`int` optional set of flags.

Returns: GDX509List* a list of end-user certificates belonging to the signer(s), or NULL. If NULL, the reason can be obtained from GDCryptoError_get().

◆ GDPKCS7_decrypt()

int GDPKCS7_decrypt	(	struct GDPKCS7 *	p7,
		struct GDKey *	pkey,
		const struct GDX509 *	cert,
		struct GDStream *	data,
		int	flags
	)

Decrypts content within a PKCS7 envelopedData structure.

Parameters

p7	`GDPKCS7*` the PKCS7 envelopedData structure to decrypt.
pkey	`GDKey*` private key of the recipient.
cert	`GDX509*` the recipients certificate.
data	`GDStream*` the decrypted content is written to data.
flags	`int` optional set of flags.

Returns: int either 1 for success or 0 for failure. The error can be obtained from GDCryptoError_get().

◆ GDPKCS7_encrypt()

struct GDPKCS7* GDPKCS7_encrypt	(	struct GDX509List *	certs,
		struct GDStream *	in,
		const struct GDCipher *	cipher,
		int	flags
	)

Create and return an encrypted PKCS7 envelopedData structure.

Parameters

certs	`GDX509List*` a list of recipient certificates.
in	`GDStream*` the content to be encrypted.
cipher	`GDCipher*` the symmetric cipher to use.
flags	`int` optional set of flags.

Returns: GDPKCS7* a PKCS7 structure or NULL if an error occurred. The error can be obtained from GDCryptoError_get().

◆ GDPKCS7_add_signer()

struct GDPKCS7* GDPKCS7_add_signer	(	const struct GDX509 *	signcert,
		struct GDKey *	pkey,
		struct GDX509List *	certs,
		const struct GDDigest *	md,
		int	flags
	)

Add signer information and return a PKCS7 signedData structure.

Parameters

signcert	`GDX509*` the signing certificate.
pkey	`GDKey*` the corresponsding private key of the signing certificate.
certs	`GDX509List*` optional additional set of certificates to include in the PKCS7 structure, for example, intermediate CAs.
md	`GDDigest*` the message digest to use.
flags	`int` optional set of flags.

Returns: GDPKCS7* a PKCS7 structure or NULL if an error occurred. The error can be obtained from GDCryptoError_get().

◆ GDPKCS7_final()

int GDPKCS7_final	(	struct GDPKCS7 *	p7,
		struct GDStream *	data,
		int	flags
	)

Finalize a PKCS7 structure, readying it for serialization. This may trigger computation of the actual PKCS7 data, such as content signing.

Parameters

p7	`GDPKCS7*` the PKCS7 structure to finalize.
data	`GDStream*` the content to be finalized.
flags	`int` optional set of flags.

Returns: int either 1 for success or 0 for failure. The error can be obtained from GDCryptoError_get().

◆ GDPKCS7_write()

int GDPKCS7_write	(	struct GDStream *	stream,
		struct GDPKCS7 *	p7,
		int	flags
	)

Serialize a PKCS7 structure to ASN.1/DER encoding suitable for sending over the network, writing to a file, and so on.

Parameters

stream	`GDStream*` the stream to write the ASN.1/DER encoded data to.
p7	`GDPKCS7*` the PKCS7 structure to serialize. The PKCS7 structure may be obtained from an initial call to GDPKCS7_add_signer() or GDPKCS7_encrypt().
flags	`int` optional set of flags.

Returns: int either 1 for success or 0 for failure. The error can be obtained from GDCryptoError_get().

◆ GDPKCS7_SMIME_write()

int GDPKCS7_SMIME_write	(	struct GDStream *	stream,
		struct GDPKCS7 *	p7,
		struct GDStream *	data,
		int	flags
	)

Serialize a PKCS7 structure to SMIME encoding suitable for sending over the network, writing to a file, and so on.

Parameters

stream	`GDStream*` the stream to write the SMIME message to.
data	`GDStream*` the content to read from if streaming is enabled.
p7	`GDPKCS7*` the PKCS7 structure to serialize. The PKCS7 structure may be obtained from an initial call to GDPKCS7_add_signer() or GDPKCS7_encrypt().
flags	`int` optional set of flags.

Returns: int either 1 for success or 0 for failure. The error can be obtained from GDCryptoError_get().

◆ GDPKCS7_free()

void GDPKCS7_free	(	struct GDPKCS7 *	p7,
		int	flags
	)

Deallocates resources held by the PKCS7 structure.

Parameters

p7	`GDPKCS7*` the PKCS7 structure to free.
flags	`int` optional set of flags.

◆ GDStream_mem_storage_method()

const struct GDStreamStorageMethod* GDStream_mem_storage_method ( void )

Retrieve a memory stream storage method required to back a stream object.

Returns: GDStream_Method* The stream storage method. If NULL, the storage method is not implemented.

◆ GDStream_new_mem_buf()

struct GDStream* GDStream_new_mem_buf	(	const void *	buf,
		int	len
	)

Creates a read-only stream from a small region of memory.

Parameters

buf	`const void*` a pointer to the beginning of the data.
len	`int` the length of the data, or -1 if the data is null-terminated.

Returns: GDStream* A read-only memory stream. If NULL, the reason can be obtained from GDCryptoError_get.

◆ GDStream_new()

struct GDStream* GDStream_new ( const struct GDStreamStorageMethod * method )

Creates a stream bakced by the specified storage method. For example, a memory stream.

Parameters

method GDStreamStorageMethod* the storage method backing the stream. For example, a memory stream from GDStream_mem_storage_method().

Returns: GDStream* A stream of the required storage method. If NULL, the reason can be obtained from GDCryptoError_get.

◆ GDStream_read()

int GDStream_read	(	struct GDStream *	stream,
		void *	data,
		int	len
	)

Read data from a stream and place it into the supplied a buffer.

Parameters

stream	`GDStream*` the stream to read from.
data	`void*` a pointer to the buffer to place the data into.
len	`len` length of the buffer.

Returns: int The number of bytes read. If -1, the reason can be obtained from GDCryptoError_get.

◆ GDStream_write()

int GDStream_write	(	struct GDStream *	stream,
		const void *	data,
		int	len
	)

Write data from the supplied buffer, into the stream.

Parameters

stream	`GDStream*` the stream to write to.
data	`void*` a pointer to the buffer to read the data from.
len	`len` length of the buffer.

Returns: int The number of bytes written. If -1, the reason can be obtained from GDCryptoError_get.

◆ GDStream_reset()

int GDStream_reset ( struct GDStream * stream )

Resets the stream to its initial state by rewinding the pointer to the start of the stream.

Parameters

stream GDStream* the stream to reset.

Returns: int 1 for success. If not 1, the error can be obtained from GDCryptoError_get.

◆ GDStream_eof()

int GDStream_eof ( struct GDStream * stream )

Tells if the stream has been completely read or not.

Parameters

stream GDStream* the stream to test.

Returns: int 1 if EOF has been reached 0 otherwise.

◆ GDStream_free()

void GDStream_free ( struct GDStream * stream )

Deallocates resources held by the stream structure.

Parameters

stream GDStream* the stream structure to free.

Variable Documentation

◆ GDCIPHER_MAX_BLOCK_LENGTH

const int GDCIPHER_MAX_BLOCK_LENGTH

Returns the maximum block length for all ciphers.

◆ GDCIPHER_MAX_KEY_LENGTH

const int GDCIPHER_MAX_KEY_LENGTH

Returns the maximum key length for all ciphers.

◆ GDDIGEST_MAX_SIZE

const int GDDIGEST_MAX_SIZE

Returns the maxmium supported digest size in bytes. As of early 2019, this value is 64, which is the size of a SHA-512 digest.

◆ GDKEY_TYPE_RSA

const int GDKEY_TYPE_RSA

Represents a RSA (Rivest–Shamir–Adleman) key type. It may be returned when calling GDKey_type(). It may also be required for some function calls requiring the key type to be specified.

◆ GDKEY_TYPE_DSA

const int GDKEY_TYPE_DSA

Represents a DSA (Digital Signature Algorithm) key type. It may be returned when calling GDKey_type(). It may also be required for some function calls requiring the key type to be specified.

◆ GDKEY_TYPE_EC

const int GDKEY_TYPE_EC

Represents a EC (Elliptic Curve) key type. It may be returned when calling GDKey_type(). It may also be required for some function calls requiring the key type to be specified.

◆ GDPKCS7_TEXT

const int GDPKCS7_TEXT

PKCS7 flags to control operations on a PKCS7 structure. These map directly to OpenSSL flags defined in pkcs7.h. Refer to OpenSSL documentation for PKCS7 functions requiring a flag argument for more information.

◆ GDPKCS7_SIGNED

const int GDPKCS7_SIGNED

If returned from GDPKCS7_type(), PKCS7 structure is signed data.

◆ GDPKCS7_ENCRYPTED

const int GDPKCS7_ENCRYPTED

If returned from GDPKCS7_type(), PKCS7 structure is encrypted data.

◆ GDPKCS7_ENVELOPED

const int GDPKCS7_ENVELOPED

If returned from GDPKCS7_type(), PKCS7 structure is enveloped data.

◆ GDPKCS7_SIGNED_AND_ENVELOPED

const int GDPKCS7_SIGNED_AND_ENVELOPED

If returned from GDPKCS7_type(), PKCS7 structure is signed and enveloped data.

◆ GDPKCS7_DATA

const int GDPKCS7_DATA

If returned from GDPKCS7_type(), PKCS7 structure is data type.

◆ GDPKCS7_DIGEST

const int GDPKCS7_DIGEST

If returned from GDPKCS7_type(), PKCS7 structure is digest data.

Functions

Variables

Detailed Description

Function Documentation

◆ GDCipher_list()

◆ GDCipher_byname()

◆ GDCipher_name()

◆ GDCipher_bycontext()

◆ GDCipher_block_size()

◆ GDCipher_key_length()

◆ GDCipher_iv_length()

◆ GDCipher_mode()

◆ GDCipher_set_padding()

◆ GDCipher_new()

◆ GDCipher_init()

◆ GDCipher_copy()

◆ GDCipher_update()

◆ GDCipher_final()

◆ GDCipher()

◆ GDCipher_cleanup()

◆ GDCipher_free()

◆ GDDigest_byname()

◆ GDDigest_name()

◆ GDDigest_bycontext()

◆ GDDigest_size()

◆ GDDigest_block_size()

◆ GDDigest_new()

◆ GDDigest_init()

◆ GDDigest_copy()

◆ GDDigest_update()

◆ GDDigest_final()

◆ GDDigest()

◆ GDDigest_sign_init()

◆ GDDigest_sign_final()

◆ GDDigest_verify_init()

◆ GDDigest_verify_final()

◆ GDDigest_cleanup()

◆ GDDigest_free()

◆ GDCryptoError_get()

◆ GDCryptoError_peek()

◆ GDCryptoError_peek_last()

◆ GDCryptoError_clear()

◆ GDCryptoError_string()

◆ GDCryptoError_detailed_string()

◆ GDFIPS_mode()

◆ GDX509_copy()

◆ GDX509_free()

◆ GDX509List_read()

◆ GDX509List_copy()

◆ GDX509List_num()

◆ GDX509List_value()

◆ GDX509List_insert()

◆ GDX509List_evaluate()

◆ GDX509List_trusted_authorities()

◆ GDX509List_all_user_certs()

◆ GDX509List_valid_user_signing_certs()

◆ GDX509List_valid_user_encryption_certs()

◆ GDX509List_all_user_encryption_certs()

◆ GDX509List_aux_certs()

◆ GDX509List_free()

◆ GDKey_public()

◆ GDKey_private()

◆ GDKey_free()

◆ GDKey_compare()

◆ GDKey_size()

◆ GDKey_bits()

◆ GDKey_type()

◆ GDKey_name()

◆ GDKeyContext_new()

◆ GDKeyContext_copy()

◆ GDKeyContext_free()

◆ GDKey_sign_init()

◆ GDKey_sign()

◆ GDKey_verify_init()

◆ GDKey_verify()

◆ GDKey_encrypt_init()

◆ GDKey_encrypt()

◆ GDKey_decrypt_init()

◆ GDKey_decrypt()

◆ GDKey_sign_final()