Skip to content

Commit

Permalink
doc: enable MSR for crypto tutorial
Browse files Browse the repository at this point in the history 
Let MSR test the crypto.md tutorial. See ElektraInitiative#1981 for full discussion.
  • Loading branch information
@petermax2
petermax2 committed Apr 14, 2019
1 parent 385c9ea commit 6eaee28
Show file tree
Hide file tree
Showing 2 changed files with 42 additions and 58 deletions.
99 changes: 41 additions & 58 deletions doc/tutorials/crypto.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,30 +47,27 @@ In this tutorial we explain the use of the `crypto` plugin and the `fcrypt` plug
We want to protect a password that is contained in an INI-file.

The following example demonstrates how the INI-file is mounted without encryption enabled.
We create the password at `user/test/password` and display the contents of `test.ini`.
We create the password at `user/tests/password` and display the contents of `test.ini`.

_Step 1:_ Mount `test.ini`

```sh
kdb set /sw/elektra/kdb/#0/current/plugins ""
sudo kdb mount test.ini user/test ini
kdb mount test.ini user/tests ini
```

_Step 2:_ Set the password at `user/test/password` and display the contents of `test.ini`
_Step 2:_ Set the password at `user/tests/password` and display the contents of `test.ini`

```sh
kdb set user/test/password 1234
#> Create a new key user/test/password with string "1234"
kdb file user/test/password | xargs cat
kdb set user/tests/password 1234
kdb file user/tests/password | xargs cat
#> password = 1234
```

_Step 3:_ (Optional) Cleanup

```sh
kdb rm user/test/password
kdb rm /sw/elektra/kdb/#0/current/plugins
sudo kdb umount user/test
kdb rm user/tests/password
kdb umount user/tests
```

As you can see the password is stored in plain text.
Expand All @@ -88,7 +85,7 @@ The `fcrypt` plugin enables the encryption and decryption of entire configuratio
The GPG key, which is used for encryption and decryption, is specified in the backend configuration under `encrypt/key`.

```bash
sudo kdb mount test.ini user/test fcrypt "encrypt/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
sudo kdb mount test.ini user/tests fcrypt "encrypt/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
```

If the above command fails, please take a look at the
Expand All @@ -111,19 +108,16 @@ gpg2 -d test.ini
The complete procedure looks like this:

```sh
kdb set /sw/elektra/kdb/#0/current/plugins ""
sudo kdb mount test.ini user/test fcrypt "encrypt/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
kdb set user/test/password 1234
#> Create a new key user/test/password with string "1234"
kdb file user/test/password | xargs cat
kdb mount test.ini user/tests fcrypt "encrypt/key=$(elektra-gpg-testkey)" ini
kdb set user/tests/password 1234
kdb file user/tests/password | xargs cat
```

To clean up the environment we run:

```sh
kdb rm user/test/password
kdb rm /sw/elektra/kdb/#0/current/plugins
sudo kdb umount user/test
kdb rm user/tests/password
kdb umount user/tests
```

## Configuration File Signatures
Expand All @@ -134,7 +128,7 @@ If `sign/key` is specified in the backend configuration, `fcrypt` will forward t
An example backend configuration is given as follows:

```bash
sudo kdb mount test.ini user/test fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
sudo kdb mount test.ini user/tests fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
```

As a result the file `test.ini` will be signed using GPG.
Expand All @@ -149,19 +143,16 @@ If `test.ini` is modified, all following calls of `kdb get` will fail with an er
The complete example looks like this:

```sh
kdb set /sw/elektra/kdb/#0/current/plugins ""
sudo kdb mount test.ini user/test fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
kdb set user/test/password 1234
#> Create a new key user/test/password with string "1234"
kdb file user/test/password | xargs cat
kdb mount test.ini user/tests fcrypt "sign/key=$(elektra-gpg-testkey)" ini
kdb set user/tests/password 1234
kdb file user/tests/password | xargs cat
```

To clean up the environment we run:

```sh
kdb rm user/test/password
kdb rm /sw/elektra/kdb/#0/current/plugins
sudo kdb umount user/test
kdb rm user/tests/password
kdb umount user/tests
```

### Combining Signatures and Encryption
Expand All @@ -171,25 +162,22 @@ The options `sign/key` and `encrypt/key` can be combined together, resulting in
Mounting `test.ini` with signatures and encryption enabled can be done like this:

```bash
sudo kdb mount test.ini user/test fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D,encrypt/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
sudo kdb mount test.ini user/tests fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D,encrypt/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
```

The complete example looks like this:

```sh
kdb set /sw/elektra/kdb/#0/current/plugins ""
sudo kdb mount test.ini user/test fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D,encrypt/key" ini
kdb set user/test/password 1234
#> Create a new key user/test/password with string "1234"
kdb file user/test/password | xargs cat
kdb mount test.ini user/tests fcrypt "sign/key=$(elektra-gpg-testkey),encrypt/key=$(elektra-gpg-testkey)" ini
kdb set user/tests/password 1234
kdb file user/tests/password | xargs cat
```

To clean up the environment we run:

```sh
kdb rm user/test/password
kdb rm /sw/elektra/kdb/#0/current/plugins
sudo kdb umount user/test
kdb rm user/tests/password
kdb umount user/tests
```

## Configuration Value Encryption/Decryption
Expand All @@ -213,7 +201,7 @@ GPG is required for the key-handling.
To follow our example of an encrypted password in `test.ini`, we first mount the INI-file with the `crypto_gcrypt` plugin enabled, like this:

```bash
sudo kdb mount test.ini user/test crypto_gcrypt "crypto/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" base64 ini
sudo kdb mount test.ini user/tests crypto_gcrypt "crypto/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" base64 ini
```

We recommend adding the `base64` plugin to the backend, because `crypto` will output binary data.
Expand All @@ -230,13 +218,13 @@ We want to protect the password, that is stored under `user/test/password`.
So we set the metakey as follows:

```bash
kdb setmeta user/test/password crypto/encrypt 1
kdb setmeta user/tests/password crypto/encrypt 1
```

Now we are safe to set the actual password:

```bash
kdb set user/test/password "1234"
kdb set user/tests/password "1234"
```

The resulting INI-file contains the following data:
Expand All @@ -249,7 +237,7 @@ password = @BASE64IyFjcnlwdG8wMBEAAADwPI+lqp+X2b6BIfLdRYgwxmAhVUPurqkQVAI78Pn4OY
You can access the password as usual with `kdb get`:

```bash
kdb get user/test/password
kdb get user/tests/password
```

As a result you get "1234".
Expand All @@ -259,37 +247,32 @@ As a result you get "1234".
You can disable the encryption by setting `crypto/encrypt` to a value other than `1`, for example:

```bash
kdb setmeta user/test/password crypto/encrypt 0
kdb setmeta user/tests/password crypto/encrypt 0
```

### Complete Example

The complete example looks like this:

```sh
kdb set /sw/elektra/kdb/#0/current/plugins ""
sudo kdb mount test.ini user/test crypto_gcrypt "crypto/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" base64 ini
kdb setmeta user/test/password crypto/encrypt 1
kdb file user/test/password | xargs cat
kdb set user/test/password 1234
#> Set string to "1234"
kdb set user/test/config "I am not encrypted"
#> Create a new key user/test/config with string "I am not encrypted"
kdb file user/test/password | xargs cat
kdb mount test.ini user/tests crypto_gcrypt "crypto/key=$(elektra-gpg-testkey)" base64 ini
kdb setmeta user/tests/password crypto/encrypt 1
kdb set user/tests/password 1234
kdb set user/tests/unencrypted "I am not encrypted"
kdb file user/tests/password | xargs cat
```

To disable encryption on `user/test/password`, we can run:
To disable encryption on `user/tests/password`, we can run:

```sh
kdb setmeta user/test/password crypto/encrypt 0
kdb file user/test/password | xargs cat
kdb setmeta user/tests/password crypto/encrypt 0
kdb file user/tests/password | xargs cat
```

To clean up the environment we run:

```sh
kdb rm user/test/config
kdb rm user/test/password
kdb rm /sw/elektra/kdb/#0/current/plugins
sudo kdb umount user/test
kdb rm user/tests/unencrypted
kdb rm user/tests/password
kdb umount user/tests
```
1 change: 1 addition & 0 deletions tests/shell/shell_recorder/tutorial_wrapper/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ if (ENABLE_ASAN)
message (STATUS "Excluding Markdown Shell Recorder test for `validation`, as it leaks memory and fails with ASAN enabled")
else (ENABLE_ASAN)
add_msr_test (tutorial_validation "${CMAKE_SOURCE_DIR}/doc/tutorials/validation.md" REQUIRED_PLUGINS ni validation)
add_msr_test (tutorial_crypto "${CMAKE_SOURCE_DIR}/doc/tutorials/crypto.md" REQUIRED_PLUGINS crypto_gcrypt fcrypt)
endif (ENABLE_ASAN)

# ========
Expand Down

0 comments on commit 6eaee28

Please sign in to comment.