Elektra: Plugin: base64

Elektra 0.8.24

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==

## 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 `@@`.

See the documentation of the null plugin, as it uses the same pattern for masking `@`.

#### Example

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

# Mount the INI and Base64 plugin
kdb mount config.ini user/tests/base64 ini 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
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 INI plugin together with Base64’s meta mode.

```<h1>Mount INI and Base64 plugin (provides`binary`) with the configuration key`binary/meta` kdb mount config.ini user/tests/base64 ini 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 setmeta 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 #>

# Undo modifications

kdb rm -r user/tests/base64 kdb umount user/tests/base64 ```

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