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 /examples/base64/test base64

. To unmount the plugin use the following command:

sudo kdb umount /examples/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/examples/base64 ini base64

# Copy binary data
kdb cp system/elektra/modules/base64/exports/get user/examples/base64/binary

# Print binary data
kdb get user/examples/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/examples/base64 | xargs cat
# STDOUT-REGEX: binary = "@BASE64[a-zA-Z0-9+/]+={0,2}"

# Undo modifications
kdb rm -r user/examples/base64
kdb umount user/examples/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 Ni and Base64 plugin (providesbinary) with the configuration keybinary/meta` kdb mount config.ini user/examples/base64 ini binary binary/meta=

Save base64 encoded data "value" (0x76616c7565)

kdb set user/examples/base64/encoded dmFsdWUA kdb file user/examples/base64/encoded | xargs cat | grep encoded #> encoded = dmFsdWUA

Tell Base64 plugin to decode and encode key value

kdb setmeta user/examples/base64/encoded type binary

Receive key data (the \x0 at the end marks the end of the string)

kdb get user/examples/base64/encoded #>

Undo modifications

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

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