Collaboration diagram for Encryption Functions:

Functions
RDM_RETCODE	rdm_dbEncrypt (RDM_DB db, RDM_ENCRYPT enc, const char *optString)
	Encrypt a database. More...

RDM_RETCODE	rdm_dbGetEncrypt (RDM_DB db, RDM_ENCRYPT *enc)
	Get the encryption context associated with a database handle. More...

RDM_RETCODE	rdm_dbSetEncrypt (RDM_DB db, RDM_ENCRYPT enc)
	Associate an encryption context with a database handle. More...

Detailed Description

Encryption API for a database. All the functions here are located in RaimaDB DB Engine Library. Linker option:

    -lrdmrdm

Additional API for instantiating an encryption context consult Encryption.

Function Documentation

rdm_dbEncrypt()

RDM_RETCODE rdm_dbEncrypt	(	RDM_DB	db,
		RDM_ENCRYPT	enc,
		const char *	optString
	)

#include <rdmdbapi.h>

Encrypt a database.

This function can encrypt, decrypt, and re-encrypt an existing RaimaDB database.

Encrypting a database: If a database is not currently encrypted the entire database (all existing tables) will be encrypted if the TABLES option is not specified or if it set to the value "TABLES=ALL". If only certain tables need to be encrypted they can be specified via a comma delimited list for the TABLES option (TABLES=table,table2,...)

Re-encrypting a database: When re-encrypting a database that is currently encrypted (the enc parameter uses a different passcode than was used to encrypt the database) the TABLES option is used to specify how the re-encryption will occur. If the TABLES option is not specified the a quick re-encrypt will occur. A quick encryption does not need to rewrite any existing data and tables that are not encrypted will remain un-encrypted. If the TABLES option is set to ALL then all tables will be fully re-encrypted (including tables that are not encrypted). A full encryption will rewrite each row in the table. If the TABLES option specifies a list of tables the will be fully re-encrypted (or encrypted if they currently are plaintext).

Decrypting a database: To decrypt a database you pass in a NULL encryption context (enc parameter). The TABLES option string specifies how the table is decrypted. If the TABLES parameter is not specified or set to ALL then all tables will be decrypted and the system encryption key will be removed. When the system encryption key is removed the database can be opened without an encryption context. If the TABLES option parameter is a comma separated list of tables then just those tables will be decrypted and the system encryption key will remain even if there are no longer any tables in the database that are encrypted.

Locking Requirements: This function requires that the database be opened in exclusive mode.

Return values

sOKAY	Normal, successful return.
eDBNOTOPEN	Database not open.
eEXCLUSIVE	Exclusive access required.
eTRACTIVE	Transaction is active.

See also: rdm_dbOpen; rdm_tfsAllocEncrypt; rdm_dbGetEncrypt; rdm-crypt

Parameters

[in]	db	A valid RaimaDB database handle
[in]	enc	The new encryption context (can be NULL to decrypt)
[in]	optString	A semicolon delimited string that contains the utility options

Examples: core18Example_main.c.

rdm_dbGetEncrypt()

RDM_RETCODE rdm_dbGetEncrypt	(	RDM_DB	db,
		RDM_ENCRYPT *	enc
	)

#include <rdmdbapi.h>

Get the encryption context associated with a database handle.

This function allows the application to retrive the encryption context associated with a database handle. It is possible that multiple encryption contexts are associated with a database handle. If that is the case this function will return the most recently associated encryption context.

Locking Requirements: None

Return values

sOKAY Normal, successful return.

See also: rdm_tfsAllocDatabase; rdm_dbSetEncrypt; rdm_tfsGetEncrypt

Parameters

[in]	db	A valid RaimaDB database handle
[in]	enc	A pointer to an encryption context

rdm_dbSetEncrypt()

RDM_RETCODE rdm_dbSetEncrypt	(	RDM_DB	db,
		RDM_ENCRYPT	enc
	)

#include <rdmdbapi.h>

Associate an encryption context with a database handle.

This function will associate an encryption context to a database handle. When a database is opened the system will us the encryption contexts associated with the handle to attempt to open the database.

Typically you would associate the encryption context to a handle prior to open a database.

You can remove all encryption contexts associated with the handle by passing in a NULL encryption context to this function.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
eDBOPEN	Database already opened in this task.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

See also: rdm_tfsAllocEncrypt; rdm_dbEncrypt; rdm_dbGetEncrypt

Parameters

[in]	db	A valid RaimaDB database handle
[in]	enc	An RDM_ENCRYPT to associate with db (can be NULL to remove all contexts associated with db)

Examples: core18Example_main.c, and core36Example_main.c.