<commit_before>- infos = Information about crypto plugin is in keys below
- infos/author = <NAME> <<EMAIL>>
- infos/licence = BSD
- infos/provides = crypto
- infos/needs =
- infos/recommends =
- infos/placements = postgetstorage presetstorage
#ifdef ELEKTRA_CRYPTO_API_GCRYPT
- infos/status = unittest configurable memleak experimental unfinished discouraged
#else
- infos/status = unittest configurable memleak experimental unfinished discouraged
#endif
- infos/metadata = crypto/encrypt
- infos/description = Cryptographic operations

## Introduction

This plugin is a filter plugin allowing Elektra to encrypt values before they are
persisted and to decrypt values after they have been read from a backend.

The idea is to provide protection of sensible values before they are persisted.
This means the value of a key needs to be encrypted before it is written to a file or a database.
It also needs to be decrypted whenever an admissible access (read) is being performed.

The users of Elektra should not be bothered too much with the internals of the cryptographic operations.
Also the cryptographic keys must never be exposed to the outside of the crypto module.

The crypto plugin supports different libraries as provider for the cryptographic operations.
At the moment the following crypto APIs are supported:

- OpenSSL (`libcrypto`)
- libgcrypt
- Botan

## Dependencies


#ifdef ELEKTRA_CRYPTO_API_GCRYPT

- `libgcrypt20-dev` or `libgcrypt-devel`

#endif


#ifdef ELEKTRA_CRYPTO_API_OPENSSL

- `libssl-dev` or `openssl-devel`

#endif


#ifdef ELEKTRA_CRYPTO_API_BOTAN

- `libbotan1.10-dev` or `botan-devel`

#endif


### GnuPG (GPG)

GPG is a runtime dependency for all crypto plugin variants.
Either the `gpg` or the `gpg2` binary should be installed when using the plugin.
Note that `gpg2` will be preferred if both versions are available.
The GPG binary can be configured in the plugin configuration as `/gpg/bin` (see _GPG Configuration_ below).
If no such configuration is provided, the plugin will look at the PATH environment variable to find the GPG binaries.

## How to compile

The following compile variants are available:

1. crypto_gcrypt
2. crypto_openssl
3. crypto_botan

Add "crypto" and the variants, that you want (you can add one of them or all), to the `PLUGINS` variable in `CMakeCache.txt` and re-run `cmake`.

In order to add all compile variants you can add "CRYPTO" to the `PLUGINS` variable.

An example `CMakeCache.txt` may contain the following variable:

    PLUGINS=crypto;crypto_gcrypt;crypto_openssl;crypto_botan

or it may look like:

    PLUGINS=CRYPTO

### Manual Library Setup

If you have a custom built OpenSSL or libgcrypt on your system, you can tell CMake to use those by setting the following CMake variables.

For a custom OpenSSL location set:

- *OPENSSL_INCLUDE_DIR* to the library's header files
- *OPENSSL_LIBRARIES* to the library's binary file

For a custom libgcrypt location set:

- *LIBGCRYPT_INCLUDE_DIR* to the library's header files
- *LIBGCRYPT_LIBRARIES* to the library's binary file

For a custom Botan development file location set:

- *BOTAN_INCLUDE_DIRS* to Botan's header files (includes)
- *BOTAN_LIBRARIES* to Botan's binary file

### Mac OS X

All variants of the plugin work under Mac OS Sierra (Version 10.12.3 (16D32)).

To set up the build environment on Mac OS Sierra we reccommend using [Homebrew](http://brew.sh/).
Follow these steps to get everything up and running:

    brew update
    brew upgrade
    brew install openssl botan libgcrypt pkg-config cmake
    # The next step is required for pkg-config to find the include files of OpenSSL
    ln -s /usr/local/opt/openssl/include/openssl/ /usr/local/include/openssl

Also a GPG installation is required. The [GPG Tools](https://gpgtools.org) work fine for us.

## Restrictions

At the moment the plugin will only run on UNIX/Linux-like systems, that provide implementations for `fork ()` and `execv ()`.

## Examples

To mount a backend with the gcrypt plugin variant that uses the GPG key 9CCC3B514E196C6308CCD230666260C14A525406, use:

    kdb mount test.ecf user/t crypto_gcrypt "crypto/key=9CCC3B514E196C6308CCD230666260C14A525406"

Now you can specify a key `user/t/a` and protect its content by using:<commit_msg>crypto: fix typo in doc<commit_after>- infos = Information about crypto plugin is in keys below
- infos/author = <NAME> <<EMAIL>>
- infos/licence = BSD
- infos/provides = crypto
- infos/needs =
- infos/recommends =
- infos/placements = postgetstorage presetstorage
#ifdef ELEKTRA_CRYPTO_API_GCRYPT
- infos/status = unittest configurable memleak experimental unfinished discouraged
#else
- infos/status = unittest configurable memleak experimental unfinished discouraged
#endif
- infos/metadata = crypto/encrypt
- infos/description = Cryptographic operations

## Introduction

This plugin is a filter plugin allowing Elektra to encrypt values before they are
persisted and to decrypt values after they have been read from a backend.

The idea is to provide protection of sensible values before they are persisted.
This means the value of a key needs to be encrypted before it is written to a file or a database.
It also needs to be decrypted whenever an admissible access (read) is being performed.

The users of Elektra should not be bothered too much with the internals of the cryptographic operations.
Also the cryptographic keys must never be exposed to the outside of the crypto module.

The crypto plugin supports different libraries as provider for the cryptographic operations.
At the moment the following crypto APIs are supported:

- OpenSSL (`libcrypto`)
- libgcrypt
- Botan

## Dependencies


#ifdef ELEKTRA_CRYPTO_API_GCRYPT

- `libgcrypt20-dev` or `libgcrypt-devel`

#endif


#ifdef ELEKTRA_CRYPTO_API_OPENSSL

- `libssl-dev` or `openssl-devel`

#endif


#ifdef ELEKTRA_CRYPTO_API_BOTAN

- `libbotan1.10-dev` or `botan-devel`

#endif


### GnuPG (GPG)

GPG is a runtime dependency for all crypto plugin variants.
Either the `gpg` or the `gpg2` binary should be installed when using the plugin.
Note that `gpg2` will be preferred if both versions are available.
The GPG binary can be configured in the plugin configuration as `/gpg/bin` (see _GPG Configuration_ below).
If no such configuration is provided, the plugin will look at the PATH environment variable to find the GPG binaries.

## How to compile

The following compile variants are available:

1. crypto_gcrypt
2. crypto_openssl
3. crypto_botan

Add "crypto" and the variants, that you want (you can add one of them or all), to the `PLUGINS` variable in `CMakeCache.txt` and re-run `cmake`.

In order to add all compile variants you can add "CRYPTO" to the `PLUGINS` variable.

An example `CMakeCache.txt` may contain the following variable:

    PLUGINS=crypto;crypto_gcrypt;crypto_openssl;crypto_botan

or it may look like:

    PLUGINS=CRYPTO

### Manual Library Setup

If you have a custom built OpenSSL or libgcrypt on your system, you can tell CMake to use those by setting the following CMake variables.

For a custom OpenSSL location set:

- *OPENSSL_INCLUDE_DIR* to the library's header files
- *OPENSSL_LIBRARIES* to the library's binary file

For a custom libgcrypt location set:

- *LIBGCRYPT_INCLUDE_DIR* to the library's header files
- *LIBGCRYPT_LIBRARIES* to the library's binary file

For a custom Botan development file location set:

- *BOTAN_INCLUDE_DIRS* to Botan's header files (includes)
- *BOTAN_LIBRARIES* to Botan's binary file

### Mac OS X

All variants of the plugin work under Mac OS Sierra (Version 10.12.3 (16D32)).

To set up the build environment on Mac OS Sierra we recommend using [Homebrew](http://brew.sh/).
Follow these steps to get everything up and running:

    brew update
    brew upgrade
    brew install openssl botan libgcrypt pkg-config cmake
    # The next step is required for pkg-config to find the include files of OpenSSL
    ln -s /usr/local/opt/openssl/include/openssl/ /usr/local/include/openssl

Also a GPG installation is required. The [GPG Tools](https://gpgtools.org) work fine for us.

## Restrictions

At the moment the plugin will only run on UNIX/Linux-like systems, that provide implementations for `fork ()` and `execv ()`.

## Examples

To mount a backend with the gcrypt plugin variant that uses the GPG key 9CCC3B514E196C6308CCD230666260C14A525406, use:

    kdb mount test.ecf user/t crypto_gcrypt "crypto/key=9CCC3B514E196C6308CCD230666260C14A525406"

Now you can specify a key `user/t/a` and protect its content by using:
{'fraction_non_alphanumeric': 0.06159802886307638, 'fraction_numerical': 0.018068755133169072, 'mean_word_length': 4.425843411839592, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4984297', 'n_tokens_mistral': 2724, 'n_tokens_neox': 2480, 'n_words': 1121}