Sample encryption plugins for a G2 data repository.
At Senzing, we strive to create GitHub documentation in a "don't make me think" style. For the most part, instructions are copy and paste. Whenever thinking is needed, it's marked with a "thinking" icon :thinking:. Whenever customization is needed, it's marked with a "pencil" icon :pencil2:. If the instructions are not clear, please let us know by opening a new Documentation issue describing where we can improve. Now on with the show...
Data in the G2 engine repository may be encrypted using an external encryption plugin. This allows for users to decide when and how to encrypt their sensitive data.
A data repository may be set up for encryption, whether it has data loaded into it previously or not. If data has been already loaded, then the data repository must be encrypted with the utility program prior to using the system.
These are the general steps for setting up G2 data encryption.
More specific details follow.
In order to use encrypted data in the data repository, the engine must be configured with an executable library with encryption/decryption methods defined. The user may use an existing library, or create their own. In this way, they may use any kind of encryption/decryption algorithm they choose.
To create such a library, a program must be compiled that implements the G2 standard encryption interface. That interface is available in the senzing-data-encryption-specification. The actual interface header file is located at g2EncryptionPluginInterface.h.
The source code for a sample library is available on GitHub. This library may be compiled on any operating system that G2 supports. When compiled, it will create two libraries:
The source code for these two plugins is meant as an example of how to create encryption plugins. For ideal security, a new plugin should be created which implements the security and data standards of the user's organization.
To enable encryption on the data repository, the engine must be set up with the encryption library in place.
Copy the encryption library into the lib folder of the G2 installation
(e.g. /opt/senzing/g2/lib).
Alternately, if you wish to have the library in a separate location,
put the new location on your system path, so that the engine may find the library.
Add needed parameters to your engine startup parameters. This will tell the engine what plugin to use, what encryption keys to use. For example, the "AES-256-CBC" sample plugin requires the following parameters in its INI setup.
Note: The parameter names may be different, depending on what kind of encryption library you are using. The parameters that are in the "DATA_ENCRYPTION" group will be made available to the encryption plugin, and they may be accessed as demonstrated in the source code for the "AES-256-CBC" sample plugin.
Example:
{
"PIPELINE": {
"SUPPORTPATH": "/opt/senzing/data",
"CONFIGPATH": "/etc/opt/senzing",
"RESOURCEPATH": "/opt/senzing/g2/resources"
},
"SQL": {
"CONNECTION": "sqlite3://na:na@/var/opt/senzing/sqlite/G2C.db"
},
"DATA_ENCRYPTION": {
"ENCRYPTION_PLUGIN_NAME": "g2EncryptDataAES256CBC",
"ENCRYPTION_KEY": "68402346802394406802620602396369",
"ENCRYPTION_INITIALIZATION_VECTOR": "6432072349624624"
}
}
If data has been previously loaded into the data repository,
then the data repository must be encrypted using the g2db2encrypt application.
This program will step through the data repository, encrypting the sensitive contents of the repository.
It can also be used to decrypt a repository.
:pencil2: Identify the g2 directory.
Example:
export SENZING_G2_DIR=/opt/senzing/g2
Command to Encrypt. Example:
cd {SENZING_G2_DIR}
./bin/g2dbencrypt -c etc/G2Module.ini -e
Command to Decrypt. Example:
cd {SENZING_G2_DIR}
./bin/g2dbencrypt -c etc/G2Module.ini -d
Note: If you are changing the method of encryption from one form to another, you must entirely decrypt the repository using the configuration for the old encryption method, and then encrypt it using the configuration for the new method.
Once the data repository has been encrypted, the engine can be used in the same manner as with unencrypted. There should be no external indications from the API that the encryption was done. The data will be seamlessly protected.
The following instructions are used when modifying and building the Docker image.
:thinking: The following tasks need to be complete before proceeding. These are "one-time tasks" which may already have been completed.
For more information on environment variables, see Environment Variables.
Set these environment variable values:
export GIT_ACCOUNT=senzing
export GIT_REPOSITORY=data-encryption-aes256cbc-sample
export GIT_ACCOUNT_DIR=~/${GIT_ACCOUNT}.git
export GIT_REPOSITORY_DIR="${GIT_ACCOUNT_DIR}/${GIT_REPOSITORY}"
Using the environment variables values just set, follow steps in clone-repository to install the Git repository.
Using command line. Example:
cd ${GIT_REPOSITORY_DIR}/src
cmake -DCMAKE_BUILD_TYPE=Release setup .
make all
make install
Using docker. Example:
cd ${GIT_REPOSITORY_DIR}
make package
The newly created binaries will be in the ${GIT_REPOSITORY_DIR}/target directory.
Alternative docker. Example:
:pencil2: Define where to put the files. Example:
export MY_OUTPUT_DIR=/tmp
Extract the files to the output directory. Example:
docker run \
--interactive \
--rm \
--tty \
--volume ${MY_OUTPUT_DIR}:/output \
senzing/data-encryption-aes256cbc-sample \
cp /results/libg2EncryptDataAES256CBC.so /output/
Using command line. Example:
cd ${GIT_REPOSITORY_DIR}/src
export CC=clang
export CXX=clang++
cmake -DCMAKE_BUILD_TYPE=Release setup .
gmake all
gmake install
Using command. Example:
cd %GIT_REPOSITORY_DIR%/src
cmake -DCMAKE_BUILD_TYPE=Release -G "Visual Studio 14 2015" -A x64 setup .
Build the project through visual studio, or via the command line.
Each plugin function has a "PREAMBLE" and "POSTAMBLE" macro. These should be included in your plugin function implementations. They help with operations such as error handling, buffer size checking, and so forth. They are meant to simplify the handling of the data being passed into and out of the plugin.
Each encrypt/decrypt call is provided with a memory buffer for returning result data. If that buffer is found to be too small, then the function should return the code value G2_ENCRYPTION_PLUGIN___OUTPUT_BUFFER_SIZE_ERROR. This will signal the G2 engine to retry, using a larger data buffer. (See the PREAMBLE/POSTAMBLE macros to see how that return code is applied.)
Content type
Image
Digest
sha256:880f4ee8c…
Size
1.5 GB
Last updated
5 months ago
docker pull senzing/data-encryption-aes256cbc-sample