| Elektra 0.11.0

Plugin: base64

- infos = Information about base64 plugin is in keys below
- infos/author = Peter Nirschl peter.nosp@m..nir.nosp@m.schl@.nosp@m.gmai.nosp@m.l.com
- infos/licence = BSD
- infos/provides = binary
- infos/needs =
- infos/recommends =
- infos/placements = postgetstorage presetstorage
- infos/status = maintained unittest nodep libc final configurable
- infos/metadata =
- infos/description = Base64 Encoding

# Base64

## Introduction

The Base64 Encoding (specified in RFC4648) is used to encode arbitrary binary data to ASCII strings.

This is useful for configuration files that must contain ASCII strings only.

The `base64` plugin encodes binary values before `kdb set` writes the configuration to the file. The values are decoded back to their original value after `kdb get` has read from the configuration file.

## Usage

To mount a simple backend that uses the Base64 encoding, you can use:

sudo kdb mount test.ecf /tests/base64/test base64

. To unmount the plugin use the following command:

sudo kdb umount /tests/base64/test

. All encoded binary values will look something like this:

@BASE64SGVsbG8gV29ybGQhCg==

. And for a null-key it will be:

@BASE64

## Modes

The plugin supports two different modes:

1. Escaping Mode
2. Meta Mode

. By default the plugin uses escaping mode which has the advantage that a storage plugin does not have to change its behavior at all to work in conjunction with Base64.

### Escaping Mode

In order to identify the base64 encoded content, the values are marked with the prefix `@BASE64`. To distinguish between the `@` as character and `@` as Base64 marker, all strings starting with `@` will be modified so that they begin with `@@`.

#### Example

The following example shows how you can use this plugin together with the TOML plugin to store binary data.

# Mount the TOML and Base64 plugin
sudo kdb mount test_config.toml user:/tests/base64 toml base64
# Copy binary data
kdb cp system:/elektra/modules/base64/exports/get user:/tests/base64/binary
# Print binary data
kdb get user:/tests/base64/binary
# STDOUT-REGEX: ^(\\x[0-9a-f]{1,2})+$
# The value inside the configuration file is encoded by the Base64 plugin
kdb file user:/tests/base64 | xargs cat
# STDOUT-REGEX: binary.*=.*"@BASE64[a-zA-Z0-9+/]+={0,2}"
# Undo modifications
kdb rm -r user:/tests/base64
sudo kdb umount user:/tests/base64

### Meta Mode

Some file formats such as YAML already support Base64 encoded data. In YAML binary data starts with the tag `!!binary` followed by a Base64 encoded scalar:

!!binary SGVsbG8sIFlBTUwh # “Hello, YAML!”

. For YAML it would not make sense to use the format of the escaping mode:

# Another YAML implementation will not be able to decode this data
# because of the prefix `@BASE64`!
!!binary "@BASE64SGVsbG8sIFlBTUwh"

. Base64 supports another mode called “meta mode”. In this mode the Base64 plugin encodes the value, but does not add a prefix. To use the escaping mode a plugin must add the configuration key `/binary/meta`. Afterwards the Base64 plugin encodes and decodes all data that contains the metakey `type` with the value `binary`.

The diagram below shows how the Base64 conversion process works in conjunction with the YAML CPP plugin.

#### Example

The following example shows you how you can use the TOML plugin together with Base64’s meta mode.

# Mount ni and Base64 plugin (provides `binary`) with the configuration key `binary/meta`
sudo kdb mount test_config.ni user:/tests/base64 ni base64 binary/meta=
# Save base64 encoded data `"value"` (`0x76616c7565`)
kdb set user:/tests/base64/encoded dmFsdWUA
kdb file user:/tests/base64/encoded | xargs cat | grep encoded
#> encoded = dmFsdWUA
# Tell Base64 plugin to decode and encode key value
kdb meta-set user:/tests/base64/encoded type binary
# Receive key data (the `\x0` at the end marks the end of the string)
kdb get user:/tests/base64/encoded
#> \x76\x61\x6c\x75\x65\x0
# Undo modifications
kdb rm -r user:/tests/base64
sudo kdb umount user:/tests/base64

For another usage example, please take a look at the ReadMe of the YAML CPP plugin.