• BlackBerry Dynamics
  • Runtime library for Android applications
  • 9.1.0.122
Crypto C Programming Interface List

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 GDCipherGDCipher_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 GDCipherGDCipher_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 GDDigestGDDigest_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 GDDigestGDDigest_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...
 
struct GDRSA * GDRSA_public_key (const struct GDX509 *cert)
 Retrieve the RSA public key. More...
 
struct GDRSA * GDRSA_private_key (const struct GDX509 *cert)
 Retrieve a pseudo private RSA key corresponding to a user certificate. More...
 
int GDRSA_size (const struct GDRSA *rsa)
 RSA modulus size. More...
 
void GDRSA_free (struct GDRSA *rsa)
 Free a RSA key structure. More...
 
int GDRSA_sign (const struct GDDigest *digest_algorithm, const void *digest, unsigned int digest_size, void *signature, unsigned int *signature_size, struct GDRSA *rsa)
 RSA sign a message digest. More...
 
int GDRSA_verify (const struct GDDigest *digest_algorithm, const void *digest, unsigned int digest_size, const void *signature, unsigned int signature_size, struct GDRSA *rsa)
 Verify an RSA signed message. More...
 
int GDRSA_public_encrypt (int flen, const void *from, void *to, struct GDRSA *rsa, int padding)
 RSA public encrypt. More...
 
int GDRSA_private_decrypt (int flen, const void *from, void *to, struct GDRSA *rsa, int padding)
 RSA private decrypt. More...
 
int GDRSA_private_encrypt (int flen, const void *from, void *to, struct GDRSA *rsa, int padding)
 RSA private encrypt. More...
 
int GDRSA_public_decrypt (int flen, const void *from, void *to, struct GDRSA *rsa, int padding)
 RSA public decrypt. 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...
 
const int GDRSA_PKCS1_PADDING
 PKCS #1 padding. More...
 
const int GDRSA_PKCS1_OAEP_PADDING
 PKCS #1 OAEP padding. More...
 
const int GDRSA_NO_PADDING
 No padding. 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
namechar* 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
ctxGDCipherContext* 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
ctxGDCipherContext* 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
cipherGDCipher* 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
cipherGDCipher* 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
cipherGDCipher* 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
cipherGDCipher* 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
ctxGDCipherContext* the cipher context for which padding is to be enabled or disabled.
paddingint 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
ctxGDCipherContext* a pointer to the cipher context.
cipherconst GDCipher* the cipher suite, for example AES-256-CBC.
keyconst void* NULL or the symmetric key to use, depending on the cipher.
ivconst void* NULL or the IV to use, depending on the cipher.
modeint 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
sourceGDCipherContext* a pointer to a cipher context.
destinationconst 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
ctxGDCipherContext* a pointer to the cipher context.
out_datavoid* 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_szsize_t the number of bytes written to out_data.
in_dataconst void* a pointer to the data to be encrypted or decrypted.
in_data_szint 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
ctxGDCipherContext* a pointer to the cipher context.
out_datasize_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_szsize_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
ctxGDCipherContext* a pointer to the cipher context.
out_datavoid* 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_dataconst void* a pointer to the data to be encrypted or decrypted.
in_data_szunsigned 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
ctxGDCipherContext* 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
ctxGDCipherContext* 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
namechar* 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
ctxGDDigestContext* 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
ctxGDDigestContext* 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
digestconst 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
digestGDCipher* 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
ctxGDDigestContext* a pointer to the digest context.
algorithmconst 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
sourceGDDigestContext* a pointer to a digest context.
destinationconst 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
ctxGDDigestContext* a pointer to the digest context.
messageconst void* a pointer to the message chunk.
message_szsize_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
ctxGDDigestContext* a pointer to the digest context.
digestvoid* 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_szsize_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
dataconst void* a buffer containing the data to hash.
data_szsize_t the size of the buffer containing the data to hash.
mdvoid* a buffer large enough to contain the digest.
md_szsize_t upon return, the number of bytes of the calculated digest.
typeGDDigest* 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
ctxGDDigestContext* the digest context to initialize.
key_contextGDKeyContext** 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.
digestGDDigest* the digest algorithm to use when signing.
keyGDKey* 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
ctxGDDigestContext* the initialized digest context to use when signing.
signaturevoid* a buffer large enough to contain the signature. If NULL, the size required is returned in signature_sz.
signature_szGDDigest* 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
ctxGDDigestContext* the digest context to initialize.
key_ctxGDKeyContext** 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.
digestGDDigest* the digest algorithm to use when verifying.
keyGDKey* 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
ctxGDDigestContext* the initialized digest context to use for verification.
signaturevoid* a buffer containing a signature.
signature_szGDDigest* 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
ctxGDDigestContext* 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
ctxGDDigestContext* 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
eunsigned 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
certGDX509* the X509 structure to copy.

◆ GDX509_free()

void GDX509_free ( struct GDX509 *  cert)

Deallocates resources held by the X509 structure.

Parameters
certGDX509* 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
pemconst char* a pointer to the PEM data.
pem_lengthint 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
certsGDX509List* 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
certsGDX509List* 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
certsGDX509List* the list of certificates to access.
indexint 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
certsGDX509List* the list of certificates to insert into.
indexint the index within the list to insert the certificate.
certGDX509* the certificate to copy and insert.
Returns
int the number of certificates within the list.

◆ 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
certsGDX509List* the certificate to evaluate, followed by intermediates (if any).
not_usedGDX509List* must be NULL.
hostnamechar* the name of the server if used to evaluate a TLS server certificate.
reasonchar** 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
certGDX509* 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
certsGDX509List* 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
certGDX509* 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
certGDX509* 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
keyGDKey* the key structure to free.

◆ GDKey_compare()

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

Compare two keys.

Parameters
aGDKey* key a.
bGDKey* 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
keyGDKey* 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
keyGDKey* 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
keyGDKey* 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
keyGDKey* 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
keyGDKey* 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
ctxGDKey* 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
ctxGDKeyContext* 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
ctxGDKeyContext* 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
ctxGDKeyContext* the key context to sign with.
signaturevoid* NULL, or a buffer large enough to hold the signature.
signature_lengthsize_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.
messagevoid* the message to sign, usually a digest.
message_lengthsize_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
ctxGDKeyContext* 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
ctxGDKeyContext* the key context to verify with.
signaturevoid* a buffer holding the signature.
signature_lengthsize_t* the length of the signature.
messagevoid* a buffer holding the message or digest to be verified.
message_lengthsize_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
ctxGDKeyContext* 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
ctxGDKeyContext* the key context to encrypt with.
encryptedvoid* a buffer large enough to hold the encrypted data. If NULL, the length required is returned in encrypted_length.
encrypted_lengthsize_t* the length of the buffer supplied to hold the encrypted data, and upon successful return the actual length of the encrypted data.
clearvoid* the data to encrypt.
clear_lengthsize_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
ctxGDKeyContext* 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
ctxGDKeyContext* the key context to decrypt with.
clearvoid* a buffer large enough to hold the decrypted data. If NULL, the length required is returned in clear_length.
clear_lengthsize_t* the length of the buffer supplied to hold the decrypted data, and upon successful return the actual length of the decrypted data.
encryptedvoid* the data to decrypt.
encrypted_lengthsize_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
digestGDDigestContext* the initialized digest context.
signaturevoid* a buffer large enough to hold the signature at least GDKey_size(key) bytes.
signature_lengthunsigned int* upon successful return will be set to the amount of data written to the signature buffer.
keyGDKey* 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
digestGDDigestContext* the initialized digest context to verify.
signaturevoid* a buffer containing the DER encoded signature.
signature_lengthunsigned int the length of the signature buffer in bytes.
keyGDKey* 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
ctxGDKeyContext* the key context to setup.
digestGDDigest* 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
ctxGDKeyContext* the key context to query.
digestGDDigest** 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
streamGDStream* the stream to read the SMIME message from.
clearTextGDStream** 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.
flagsint 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
streamGDStream* the stream to read the ASN.1/DER encoded data from.
flagsint 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
p7GDPKCS7* the PKCS7 structure to verify. The PKCS7 structure may be obtained from an initial call to GDPKCS7_read(), GDPKCS7_encrypt(), or GDPKCS7_add_signer().
flagsint 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
p7GDPKCS7* the PKCS7 structure to verify. The PKCS7 structure may be obtained from an initial call to GDPKCS7_read().
certsGDX509List* a set of certificates in which to search for the signer's certificate.
anchorsGDX509List* an optional set of trusted certificate authorities or NULL if using the Dynamics trusted certificate store.
indataGDStream* the signed data if the content is detached.
outGDStream* the content is written to out if it is not NULL.
flagsint 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
p7GDPKCS7* the PKCS7 signedData. The PKCS7 structure may be obtained from an initial call to GDPKCS7_read().
flagsint 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
p7GDPKCS7* the PKCS7 envelopedData structure to decrypt.
pkeyGDKey* private key of the recipient.
certGDX509* the recipients certificate.
dataGDStream* the decrypted content is written to data.
flagsint 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
certsGDX509List* a list of recipient certificates.
inGDStream* the content to be encrypted.
cipherGDCipher* the symmetric cipher to use.
flagsint 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
signcertGDX509* the signing certificate.
pkeyGDKey* the corresponsding private key of the signing certificate.
certsGDX509List* optional additional set of certificates to include in the PKCS7 structure, for example, intermediate CAs.
mdGDDigest* the message digest to use.
flagsint 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
p7GDPKCS7* the PKCS7 structure to finalize.
dataGDStream* the content to be finalized.
flagsint 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
streamGDStream* the stream to write the ASN.1/DER encoded data to.
p7GDPKCS7* the PKCS7 structure to serialize. The PKCS7 structure may be obtained from an initial call to GDPKCS7_add_signer() or GDPKCS7_encrypt().
flagsint 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
streamGDStream* the stream to write the SMIME message to.
dataGDStream* the content to read from if streaming is enabled.
p7GDPKCS7* the PKCS7 structure to serialize. The PKCS7 structure may be obtained from an initial call to GDPKCS7_add_signer() or GDPKCS7_encrypt().
flagsint 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
p7GDPKCS7* the PKCS7 structure to free.
flagsint optional set of flags.

◆ GDRSA_public_key()

struct GDRSA* GDRSA_public_key ( const struct GDX509 *  cert)
Deprecated:
Use GDKey_public().

Return the RSA public key from within the supplied certificate.

Parameters
certGDX509* the certificate for which the key is required.
Returns
GDRSA* the public key of the certificate. If NULL, the reason can be obtained from GDCryptoError_get().

◆ GDRSA_private_key()

struct GDRSA* GDRSA_private_key ( const struct GDX509 *  cert)
Deprecated:
Use GDKey_private().

Return the private RSA key corresponding to a user certificate. The key data is not meaningful and will yield garbage if used to sign or decrypt data using non-Dynamics APIs.

Parameters
certGDX509* the certificate for which the private key is required.
Returns
GDRSA* the RSA private key of the certificate. If NULL, the reason can be obtained from GDCryptoError_get().

◆ GDRSA_size()

int GDRSA_size ( const struct GDRSA *  rsa)
Deprecated:
Use GDKey_size().

Returns the RSA modulus size in bytes. It can be used to determine how much memory must be allocated for an RSA encrypted value.

Parameters
rsaGDRSA* the RSA key for which the modulus size is required.
Returns
int the RSA modulus size in bytes.

◆ GDRSA_free()

void GDRSA_free ( struct GDRSA *  rsa)
Deprecated:
Use GDKey_free().

Deallocates resources held by the RSA key structure.

Parameters
rsaGDRSA* the RSA key structure to free.

◆ GDRSA_sign()

int GDRSA_sign ( const struct GDDigest digest_algorithm,
const void *  digest,
unsigned int  digest_size,
void *  signature,
unsigned int *  signature_size,
struct GDRSA *  rsa 
)
Deprecated:
Use GDDigest_sign_final().

RSA sign a message digest specified in PKCS #1 v2.0.

Parameters
digest_algorithmconst GDDigest* the digest algorthim of the message.
digestconst void* a pointer to a buffer containing the message digest.
digest_sizeunsigned int the digest size.
signaturevoid* a pointer to memory large enough to contain the signature. The caller must allocate and eventually free this buffer. The size of the buffer required can be determined by calling GDRSA_size().
signature_sizeunsigned int the number of signature bytes copied to signature.
rsaGDRSA* the signer's RSA private key.
Returns
int 1 on success, 0 for failure.

◆ GDRSA_verify()

int GDRSA_verify ( const struct GDDigest digest_algorithm,
const void *  digest,
unsigned int  digest_size,
const void *  signature,
unsigned int  signature_size,
struct GDRSA *  rsa 
)
Deprecated:
GDDigest_verify_final().

Verify an RSA signed message.

Parameters
digest_algorithmconst GDDigest* denotes the message digest algorithm that was used to generate the signature.
digestconst void* a pointer to a buffer containing the digest of the message to verify.
digest_sizeunsigned int the message digest size in bytes.
signatureconst void* a pointer to the RSA signature.
signature_sizeunsigned int the size of the RSA signature.
rsaGDRSA* the signer's RSA public key.
Returns
int 1 on successful verification, 0 for failure. The reason for failure can be determined by calling GDCryptoError_get().

◆ GDRSA_public_encrypt()

int GDRSA_public_encrypt ( int  flen,
const void *  from,
void *  to,
struct GDRSA *  rsa,
int  padding 
)
Deprecated:
Use GDKey_encrypt().

RSA encrypt a message with the recipient's public key.

Parameters
flenint the size of the data to be encrypted.
fromconst void* a pointer to the data (usually a symmetric key) to be encrypted.
tovoid* a pointer to memory large enough to contain the encrypted data. The caller must allocate and eventually free this buffer. The size of the buffer required can be determined by calling GDRSA_size().
rsaGDRSA* the recipient's public key.
paddingint the padding scheme to use.
Returns
int if successful, the size in bytes of the encrypted data, or -1 if not. The reason for failure can be determined by calling GDCryptoError_get().

◆ GDRSA_private_decrypt()

int GDRSA_private_decrypt ( int  flen,
const void *  from,
void *  to,
struct GDRSA *  rsa,
int  padding 
)
Deprecated:
Use GDKey_decrypt().

RSA decrypt a message with the recipient's private key.

Parameters
flenint the size of the data to be decrypted.
fromconst void* a pointer to the data (usually a symmetric key) to be decrypted.
tovoid* a pointer to memory large enough to contain the decrypted data. The caller must allocate and eventually free this buffer. The size of the buffer required can be determined by calling GDRSA_size().
rsaGDRSA* the recipient's private key.
paddingint the padding scheme to use.
Returns
int if successful, the size in bytes of the decrypted data, or -1 if not. The reason for failure can be determined by calling GDCryptoError_get().

◆ GDRSA_private_encrypt()

int GDRSA_private_encrypt ( int  flen,
const void *  from,
void *  to,
struct GDRSA *  rsa,
int  padding 
)
Deprecated:
Use GDKey_encrypt().

RSA encrypt a message with the recipient's private key. This is a low-level signing operation. To generate an RSA signature, call GDRSA_sign().

Parameters
flenint the size of the data to be encrypted.
fromconst void* a pointer to the data (usually a message digest) to be encrypted.
tovoid* a pointer to memory large enough to contain the encrypted data. The caller must allocate and eventually free this buffer. The size of the buffer required can be determined by calling GDRSA_size().
rsaGDRSA* the signer's private key.
paddingint the padding scheme to use.
Returns
int if successful, the size in bytes of the encrypted data, or -1 if not. The reason for failure can be determined by calling GDCryptoError_get().

◆ GDRSA_public_decrypt()

int GDRSA_public_decrypt ( int  flen,
const void *  from,
void *  to,
struct GDRSA *  rsa,
int  padding 
)
Deprecated:
Use GDKey_decrypt().

RSA decrypt a message with the sender's public key. This is a low-level verification operation. To verify an RSA signature, call GDRSA_verify().

Parameters
flenint the size of the data to be decrypted.
fromconst void* a pointer to the data (usually a message digest) to be decrypted.
tovoid* a pointer to memory large enough to contain the decrypted data. The caller must allocate and eventually free this buffer. The size of the buffer required can be determined by calling GDRSA_size().
rsaGDRSA* the sender's public key.
paddingint the padding scheme to use.
Returns
int if successful, the size in bytes of the decrypted data, or -1 if not. The reason for failure can be determined by calling GDCryptoError_get().

◆ 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
bufconst void* a pointer to the beginning of the data.
lenint 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
methodGDStreamStorageMethod* 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
streamGDStream* the stream to read from.
datavoid* a pointer to the buffer to place the data into.
lenlen 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
streamGDStream* the stream to write to.
datavoid* a pointer to the buffer to read the data from.
lenlen 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
streamGDStream* 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
streamGDStream* 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
streamGDStream* 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.

◆ GDRSA_PKCS1_PADDING

const int GDRSA_PKCS1_PADDING
Deprecated:
Use GDCryptoKeyStore.h which is a generic API that can handle RSA, DSA, and EC keys.

Returns a constant representing a PKCS #1 v1.5 padding scheme.

◆ GDRSA_PKCS1_OAEP_PADDING

const int GDRSA_PKCS1_OAEP_PADDING
Deprecated:
Use GDCryptoKeyStore.h which is a generic API that can handle RSA, DSA, and EC keys.

Returns a constant representing a EME-OAEP padding scheme, as defined in PKCS #1 v2.0.

◆ GDRSA_NO_PADDING

const int GDRSA_NO_PADDING
Deprecated:
Use GDCryptoKeyStore.h which is a generic API that can handle RSA, DSA, and EC keys.

Returns a constant representing no padding scheme.