NAME

ftimes-encoder - Encode/Decode strings/records using various algorithms

SYNOPSIS

ftimes-encoder [-o option[,option[,...]]] [-t type] [-x xformer[[:arg[,arg[...]][:slot]]] -m mode -f {file|-}

DESCRIPTION

This utility reads lines from a file or stdin and encodes or decodes them according to user-specified criteria.

OPTIONS

-f {file|-}

Specifies the name of the input file. A value of '-' will cause the program to read from stdin.

-m mode

Specifies the mode of operation. The mode can be one of {e|enc|encode}, {d|dec|decode}, or {c|con|convert}. Note that the following conversion tuples are supported:

    hex:base32             or  base32:hex
    hex:base64             or  base64:hex
    hex:base64url          or  base64url:hex
    hex:ftimes-url         or  ftimes-url:hex
    hex:hex-array          or  hex-array:hex
    hex:hex-cstring        or  hex-cstring:hex
    hex-array:hex-cstring  or  hex-cstring:hex-array
    hex:url                or  url:hex

Additionally, any type may be converted to itself (e.g., hex:hex).

-o option,[option[,...]]

Specifies the list of options to apply. Currently, the following options are supported:

NoNewline

Don't add a newline character to the end of the output. This option is primarily intended for single line decodes where the output is expected to be binary and subsequently redirected to a file or piped to another utility. In both of these cases, the extra newline would be unwanted since it will pollute the output stream.

OneString

Treat the entire input stream as a single string. This option is primarily intended for small- to medium-sized input streams that can easily be stored in memeory.

NixSpaces

Remove all spaces (i.e., ' ') from the input prior to operating on the remaining data.

-t type

Specifies the type of encoding or decoding to apply. The type can be one of {b32,base32}, {b64,base64}, {b64url,base64url}, bookend-hex, ftimes-nss, ftimes-sss, ftimes-url, hex, safe-bookend-hex, or url. NSS is short for Neuter Safe String, and SSS is short for Shell Safe String.

-x xformer[[:arg[,arg[...]][:slot]]

Specifies a transformer tuple used to manipulate the data before, between, or after the requested encoder, converter, or decoder operation where

xformer[:arg[,arg[...]]]

Specifies a transformer function (including arguments if any) that is to be used to manipulate the data before encoding (in encode mode), after decoding (in decode mode), or between decoding/encoding (in convert mode). Refer to the TRANSFORMERS section for details on supported functions and their arguments.

slot

Specifies the slot (or relative order) of this particular transformer when multiple transformers are in play. For example, transformers with user-specified slots of 1, 2, and 3 will be executed 1st, 2nd, and 3rd, respectively. If slot is not specified, it will be assigned based on the order in which -x arguments are processed. Numbering begins at 1 and increments by 1 thereafter.

Note that the slot designator is reserved for future use. Thus, only one -x argument per invocation is supported at this time. If multiple -x arguments are specified, only the last one will be recognized.

TRANSFORMERS

Each transformer has an implicit data argument, which is supplied as the first argument by this script.

and(key)

This transformer ANDs each byte (or block of bytes) using the specified key, which is expected to be a hex byte sequence of arbitrary size. The size of the key establishes the block size. If not specified, a default value of 0xff is used as the key, which effectively makes this transformer perform the same as nop().

nop()

This transformer does nothing.

rot13()

This transformer performs the ROT13 substitution cipher on qualified bytes (i.e., bytes that map to characters in the set [A-Za-z]).

rot47()

This transformer performs the ROT47 substitution cipher on qualified bytes (i.e., bytes that map to characters in the set [!-~]).

not()

This transformer inverts (i.e., performs a 1's complement on) every byte.

xor(key, padding)

This transformer XORs each byte (or block of bytes) using the specified key, which is expected to be a hex byte sequence of arbitrary size. The size of the key establishes the block size. If not specified, a default value of 0x00 is used as the key, which effectively makes this transformer perform the same as nop().

If padding is required, it must be specified as a hex byte sequence of arbitrary size. Note that padding is only appended to data if the result of (data % key) yields a remainder. Since any number mod 1 equals 0, do not expect padding to be appended when the key size is 1 byte. Extra padding (i.e., anything beyond what is needed to reach the next block boundary) is ignored. If the data buffer size is already an integral multiple of the block size, no padding will be added (even if it was specified).

EXAMPLES

Example 1. Base64 Encode

This example demonstrates how to base64-encode a given input string.

    echo -n '{"a":1,"b":2,"c":3}' | \
      ftimes-encoder -m encode -t base64 -f -

Example 2. Base64 Decode

This example demonstrates how to base64-decode a given input string.

    echo -n 'eyJhIjoxLCJiIjoyLCJjIjozfQ==' | \
      ftimes-encoder -m decode -t base64 -f -

Example 3. Base64 to Hex Conversion

This example demonstrates how to convert a base64 string to hex.

    echo -n 'eyJhIjoxLCJiIjoyLCJjIjozfQ==' | \
      ftimes-encoder -m convert -t base64:hex -f -

Example 4. Hex to Base64 Conversion

This example demonstrates how to convert a hex string to base64.

    echo -n '7b2261223a312c2262223a322c2263223a337d' | \
      ftimes-encoder -m convert -t hex:base64 -f -

Example 5. JWT Token Decode

This example demonstrates how to base64-decode a JWT token, which has the following format:

    [base64url(header)].[base64url(payload)].[base64url(signature)]

Given the following token components:

    HEADER="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
    PAYLOAD="eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ"
    SIGNATURE="SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

The JWT token becomes:

    JWT_TOKEN="${HEADER}.${PAYLOAD}.${SIGNATURE}"

Since the third field is a signature and its decoded output will likely consist of raw bytes, we'll want to break the decode process into two steps. In step one, we decode the header and payload like so:

    echo -n "${JWT_TOKEN}" | tr '.' '\n' | head -n 2 | \
      ftimes-encoder -m decode -t base64url -f -

In step two, we convert the signature from base64 to hex like so:

    echo -n "${JWT_TOKEN}" | tr '.' '\n' | tail -n 1 | \
      ftimes-encoder -m convert -t base64url:hex -f -

Note that the sole purpose of the JWT_TOKEN variable defined above was to make the commands presented in this example more readable.

Example 6. XOR Transformer

This example demonstrates how to base64-decode a string, and XOR every byte with a key of 0x20.

    echo -n "WlpaWlpaWlo=" | \
      ftimes-encoder -m decode -t base64 -x xor:20 -f -

Example 7. XOR Transformer Multi-Byte Key

This example demonstrates how to XOR two hex strings, one acting as input and the other the key. Under the hood, each byte in the input string is being XOR'd against the corresponding byte in the key. Note that the key is reused for each block of input.

    echo -n "a5a5a5a501010101" | \
      ftimes-encoder -m convert -t hex:hex -x xor:5a5a5a5a -f -  

AUTHOR

Klayton Monroe

SEE ALSO

ftimes(1), ftimes-xformer(1)

LICENSE

All documentation and code are distributed under same terms and conditions as FTimes.