https://github.com/ab/sixword

Encode binary data for humans. Implementation of RFC 2289 compatible 6-word encoding
https://github.com/ab/sixword

Last synced: about 1 month ago
JSON representation

Encode binary data for humans. Implementation of RFC 2289 compatible 6-word encoding

• Host: GitHub
• URL: https://github.com/ab/sixword
• Owner: ab
• License: gpl-3.0
• Created: 2013-09-25T06:13:45.000Z (over 11 years ago)
• Default Branch: master
• Last Pushed: 2021-10-05T17:23:19.000Z (about 3 years ago)
• Last Synced: 2024-11-10T20:45:19.127Z (about 2 months ago)
• Language: Ruby
• Homepage:
• Size: 78.1 KB
• Stars: 9
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE.txt

Awesome Lists containing this project

README

        
# Sixword

[![Gem Version](https://badge.fury.io/rb/sixword.svg)](https://rubygems.org/gems/sixword)

[![Build status](https://github.com/ab/sixword/actions/workflows/tests.yml/badge.svg)](https://github.com/ab/sixword/actions/workflows/tests.yml)

[![Code Climate](https://codeclimate.com/github/ab/sixword.svg)](https://codeclimate.com/github/ab/sixword)

[![Inline Docs](http://inch-ci.org/github/ab/sixword.svg?branch=master)](http://www.rubydoc.info/github/ab/sixword/master)

Sixword implements the 6-word binary encoding created for S/Key (tm) and

standardized by RFC 2289, RFC 1760, and RFC 1751. Binary data may be

encoded using a dictionary of 2048 English words of 1-4 characters in

length. Each block of 64 bits is encoded using 6 words, which includes 2

parity bits. It is ideal for transmitting binary data such as cryptographic

keys where humans must communicate or enter the values.

## Comparison to other encodings

See also: Bubble Babble, PGP Word List, Diceware, Base64, Base32

- Bubble Babble does not use full words, so it is more difficult for humans to

  type or communicate over the phone.

- The PGP Word List is optimized for communicating fingerprints, so it uses

  much longer and more distinct words. This is less convenient when you

  actually expect a human to type the whole sentence. Sixword handles error

  detection with the built-in parity bits.

- Diceware is optimized for creating passphrases by a roll of standard 6-sided

  dice, so it uses a word list that is a power of 6. This is not very

  convenient as an encoding for arbitrary binary data.

- Base64 is well suited as a machine encoding where an ASCII transport is

  desired. It is not very convenient for humans, and has no parity built in.

- Base32 is somewhat better for humans than Base64 because it is case

  insensitive and doesn't include 0 or 1. However it is still not very

  convenient for humans to type or visually inspect.

## Installation

Add this line to your application's Gemfile:

    gem 'sixword'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install sixword

## Usage: Command Line

Sixword operates similarly to `base64(1)`, it operates on a file or on STDIN in two modes:

- encode: accept binary data (or hexadecimal in hex modes) and print six-word

  encoded data on stdout.

- decode: accept six-word encoded data and print binary data (or hex) on

  stdout.

### Examples

Normal encoding and decoding

    $ sixword <<< 'Testing'

    BEAK NET SITE ROTH SWIM FORM

    $ sixword -d <<< 'BEAK NET SITE ROTH SWIM FORM'

    Testing

    $ sixword -d <<< 'beak net site roth swim form'

    Testing

The same data, but hex encoded

    $ sixword -H <<< '54:65:73:74:69:6e:67:0a'

    BEAK NET SITE ROTH SWIM FORM

    $ sixword -dH <<< 'BEAK NET SITE ROTH SWIM FORM'

    54657374696e670a

    $ sixword -df <<< 'BEAK NET SITE ROTH SWIM FORM'

    5465 7374 696E 670A

    $ sixword -d -S colons <<< 'BEAK NET SITE ROTH SWIM FORM'

    54:65:73:74:69:6e:67:0a

Error handling

    $ sixword -d <<< 'BEAK NET SITE ROTH SWIM FOR'

    sixword: Parity bits do not match

    [exit status 3]

    $ sixword -p <<< '.'

    sixword: Must pad bytes to multiple of 8 or use pad_encode

## Usage: Library

See the [YARD documentation](http://www.rubydoc.info/github/ab/sixword/master).

The top-level `Sixword` module contains the main API (`Sixword.encode` and

`Sixword.decode`), while various utilities can be found in `Sixword::Hex` and

`Sixword::Lib`. Most of the code powering the command line interface is in

`Sixword::CLI`.

    >> require 'sixword'

    >> Sixword.encode('Hi world')

    => ["ACRE", "ADEN", "INN", "SLID", "MAD", "PAP"]

    >> Sixword.decode(["ACRE", "ADEN", "INN", "SLID", "MAD", "PAP"])

    => 'Hi world'

    >> Sixword.decode("acre aden inn slid mad pap")

    => 'Hi world'

## Contributing

1. Fork it

2. Create your feature branch (`git checkout -b my-new-feature`)

3. Commit your changes (`git commit -am 'Add some feature'`)

4. Push to the branch (`git push origin my-new-feature`)

5. Create new Pull Request