sixword 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b74ea6c562414ef7a07f742098179f75bccb9807cd5e75161d5f8cb2a04ee780
-  data.tar.gz: 9e5842fc333709e4469d518d5fcffd90987a60fff2c070892923e69dcff19c93
+  metadata.gz: feb344c9058b513d794ccab85edbd778cce35d3f858ae7a980ad40c8cebc9ec2
+  data.tar.gz: 49726f7f0ea5f242a3a4091ab56553147ad96d5ed110b8283b10b6cef7f39644
 SHA512:
-  metadata.gz: 8b238947058e4b05daadb950f3c67f72c7ace5982d97b7e7ec68ad5047ec93ccf3b82af3b0cd9956296e04b1f625a6c0d755db6f3443612ba947a5cf68a16a9d
-  data.tar.gz: 05d8e291207ad2fcc499584a7647de32ef7f9c4a41a2d9d6b35c0a8629de7eb552e880e938a3990fa4ea2a52f8b22b618372b1bc05c2981104027da028d0eb27
+  metadata.gz: f5a60cc54e7c31beefa84c8f4a9532db95f397770109cffad1e7b314f38758505915cfbf13119094357c4b9bc4d5def43b36a67eaf4332a70a19b2ba66b2231f
+  data.tar.gz: f5991b440d27855a484630a35638203dae59f1ca4c26868316cf7a8b9c9588837522b40701483c11721c4e9bc45ea712abea08bd6c6cd4c9556f333bae3871c5

data/.github/workflows/tests.yml

@@ -7,10 +7,10 @@ jobs:
       matrix:
         os: [ubuntu-latest]  #, macos-latest
         # Due to https://github.com/actions/runner/issues/849, we have to use quotes for '3.0'
-        ruby: [2.6, 2.7, '3.0', head, jruby, jruby-head]
+        ruby: ['3.0', 3.1, 3.2, 3.3, 3.4, head, jruby, jruby-head]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}

data/CHANGELOG.md

@@ -4,6 +4,15 @@ This project adheres to [Semantic Versioning](http://semver.org).
 
 ## [Unreleased]
 
+## [0.5.0] -- 2025-09-17
+
+- Require ruby version >= 3.0.
+- Update dependencies and test on newer ruby versions.
+- Add a base64 encoding/decoding mode.
+- Fix a minor bug with hex style colons.
+- Refactor help text to be easier to follow.
+
+
 ## [0.3.5] -- 2018-03-28
 
 - Fix up rubocop config etc.

data/bin/sixword

@@ -17,50 +17,41 @@ usage: #{BaseName} [OPTION]... [FILE]
 
 Six-word encode or decode FILE, or standard input, to standard output.
 
-The data are encoded using the 2048 word dictionary created for S/Key (tm) and
-standardized by RFC 2289, RFC 1760, and RFC 1751. It also supports an optional
-custom padding scheme to allow for messages that are not a multiple of 8 bytes.
+Binary encoding for humans
 
-With no FILE, or when FILE is -, read standard input.
-
-#{BaseName} understands a few different styles of hexadecimal input and output.
-When encoding, the input will first be decoded to binary data before being
-encoded to words. When decoding, the output will be encoded in hex.
-
-
-Hex styles:
+#{BaseName} is similar to base64, but intended for humans to read and type.
+The six-word encoding uses a dictionary of 2048 short English words.
+Each 8-byte input becomes 6 words of output, including 2 checksum bits.
+This makes it easy to read and type quickly with built-in error checking.
 
-  lower/lowercase:
-    Accept a variety of inputs, but don't include whitespace in output.
+Use cases include sharing cryptographic keys on paper, verifying fingerprints,
+or comparing binary data.
 
-    Encoding:
-      '48:69:20:77:6f:72:6c:64' => 'Hi world' => 'ACRE ADEN INN SLID MAD PAP'
-    Decoding:
-      'ACRE ADEN INN SLID MAD PAP' => 'Hi world' => '486920776f726c64'
-
-  finger/fingerprint:
-    Accept a variety of inputs, and include whitespace in output.
-    This is intended to look something like GPG fingerprints.
-
-    Encoding:
-      '4869 2077 6F72 6C64' => 'Hi world' => 'ACRE ADEN INN SLID MAP PAP'
-    Decoding:
-      'ACRE ADEN INN SLID MAP PAP' => 'Hi world' => '4869 2077 6F72 6C64'
+The six-word encoding was created for S/Key (tm) and standardized by RFC 2289,
+RFC 1760, and RFC 1751. This #{BaseName} implementation also supports an
+optional non-standard padding scheme to allow for messages that are not a
+multiple of 8 bytes.
 
+With no FILE, or when FILE is -, read standard input.
 
 Options:
     EOM
 
-    opts.on('-h', '--help', 'Display this message', ' ') do
+    opts.on('-h', '--help', 'Display this message') do
       $stderr.puts opts, ''
       exit 0
     end
-    opts.on('-v', '--version', 'Print version number', ' ') do
+
+    # --
+    opts.separator('')
+
+    opts.on('-v', '--version', 'Print version number') do
       puts 'sixword ' + Sixword::VERSION
       exit 0
     end
 
-    #
+    # --
+    opts.separator('')
 
     opts.on('-d', '--decode', 'Decode data') do
       options[:mode] = :decode
@@ -70,32 +61,137 @@ Options:
       options[:mode] = :encode
     end
 
-    opts.on('-p', '--no-pad', "Don't use custom padding scheme", ' ') do
+    opts.on('-p', '--no-pad', "Don't use custom padding scheme") do
       options[:pad] = false
     end
 
-    #
+    # --
+    opts.separator('')
+
+    opts.on('-S', '--style STYLE',
+            'Use STYLE as format/coding for plain text') do |style|
+      options[:style] = style
+    end
 
-    opts.on('-S', '--hex-style STYLE',
-            'Treat input (when encoding) or print',
-            'output (when decoding) as hex') do |style|
-      options[:hex_style] = style
+    opts.on('--hex-style STYLE', 'Alias for --style') do |style|
+      options[:style] = style
+    end
+
+    opts.on('-B', '--base64', 'Use base64 input/output') do
+      options[:style] = 'base64'
     end
 
     opts.on('-H', '--hex', 'Short for --hex-style lowercase') do
-      options[:hex_style] = 'lowercase'
+      options[:style] = 'lowercase'
     end
 
-    opts.on('-f', '--fingerprint', 'Short for --hex-style fingerprint', ' ') do
-      options[:hex_style] = 'fingerprint'
+    opts.on('-f', '--fingerprint', 'Short for --hex-style fingerprint') do
+      options[:style] = 'fingerprint'
     end
 
-    #
+    # --
+    opts.separator('')
 
     opts.on('-w', '--line-width NUM',
             'Print NUM sentences per line when encoding') do |arg|
       options[:line_width] = Integer(arg)
     end
+
+    opts.separator('')
+
+
+    opts.separator <<-EOM
+Encoding Styles:
+
+#{BaseName} understands a few different styles of hexadecimal input and output.
+When encoding, the input will first be decoded to binary data before being
+encoded to words. When decoding, the output will be encoded in hex.
+
+The --style STYLE option can be used to encode to / decode from formats other
+than raw binary bytes. This is useful when interacting with binary data like a
+key that is already encoded in hex or base64.
+
+For example, with --style base64, input for encode is assumed to be base64, and
+output from decode will be base64.
+
+This table shows how the 8 bytes "Hi world" would be encoded in each style.
+(Sixword: "ACRE ADEN INN SLID MAD PAP")
+
+  ╭─────────────────────┬─────────────────────────╮
+  │        Style        │   Example input/output  │
+  ├─────────────────────┼─────────────────────────┤
+  │ <default>           │ Hi world                │
+  │ base64              │ SGkgd29ybGQ=            │
+  │ lower, lowercase    │ 486920776f726c64        │
+  │ finger, fingerprint │ 4869 2077 6F72 6C64     │
+  │ colons              │ 48:69:20:77:6f:72:6c:64 │
+  ╰─────────────────────┴─────────────────────────╯
+
+The hex styles all accept hexadecimal input in a variety of formats.
+They allow `a-fA-F0-9` and ignore whitespace and certain punctuation: `:.-`
+(colon, period, hyphen).
+
+Examples:
+
+  Normal encoding and decoding:
+
+    $ echo 'Testing' | sixword
+    BEAK NET SITE ROTH SWIM FORM
+
+    $ sixword -d <<< 'BEAK NET SITE ROTH SWIM FORM'
+    Testing
+
+    $ sixword -d <<< 'beak net site roth swim form'
+    Testing
+
+
+  Random 128-bit (16 byte) key:
+
+    $ head -c 16 /dev/urandom | sixword
+    THIS IOTA DOUG FELT OIL MITT
+    LIED LAIN AND HULK MADE LAUD
+
+    $ cat > key.txt
+    this iota doug felt oil mitt
+    lied lain and hulk made laud
+
+    $ sixword -d key.txt | xxd
+    00000000: eab3 ddd7 bf92 f179 ae35 3008 ce4b 5b56  .......y.50..K[V
+
+
+  With encoding styles:
+
+    $ 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 --style colons <<< 'BEAK NET SITE ROTH SWIM FORM'
+    54:65:73:74:69:6e:67:0a
+
+    $ sixword -d --style base64 <<< 'BEAK NET SITE ROTH SWIM FORM'
+    VGVzdGluZwo=
+
+    $ sixword -d <<< 'BEAK NET SITE ROTH SWIM FORM' | base64
+    VGVzdGluZwo=
+
+
+  Errors:
+
+    $ sixword -d <<< 'BEAK NET SITE ROTH SWIM FOR'
+    sixword: Parity bits do not match
+    [exit status 3]
+
+    $ echo 'abc' | sixword --no-pad
+    sixword: Must pad bytes to multiple of 8 or use pad_encode
+    [exit status 10]
+
+    EOM
+
   end
 
   begin

data/lib/sixword/cli.rb

@@ -1,3 +1,5 @@
+require 'base64'
+
 module Sixword
 
   # The Sixword::CLI class implements all of the complex processing needed for
@@ -26,7 +28,8 @@ module Sixword
     #
     # @option options [:encode, :decode] :mode (:encode)
     # @option options [Boolean] :pad (false)
-    # @option options [String] :hex_style
+    # @option options [String] :style
+    # @option options [String] :hex_style Alias of :style
     # @option options [Integer] :line_width (1) In encode mode, the number of
     #   sentences to output per line.
     #
@@ -62,15 +65,25 @@ module Sixword
       mode == :encode
     end
 
+    # Return the value of the :style option.
+    # @return [String, nil]
+    def style
+      options[:style] || options[:hex_style]
+    end
+
     # Return the value of the :hex_style option.
+    # @deprecated Use {#style} instead.
     # @return [String, nil]
     def hex_style
-      options[:hex_style]
+      options[:style] || options[:hex_style]
     end
 
     # Format data as hex in various styles.
     def print_hex(data, chunk_index, cols=80)
       case hex_style
+      when 'b64', 'base64'
+        # encode as base64
+        print Base64.strict_encode64(data)
       when 'lower', 'lowercase'
         # encode to lowercase hex with no newlines
         print Sixword::Hex.encode(data)
@@ -121,8 +134,15 @@ module Sixword
         raise ArgumentError.new("block is required")
       end
 
-      read_input_by_6_words do |arr|
-        yield Sixword.decode(arr, padding_ok: pad?)
+      # base64 decoding must happen in one shot to avoid inserting unnecessary
+      # padding in the middle
+      if hex_style == 'base64' || hex_style == 'b64'
+        yield Sixword.decode(stream.read, padding_ok: pad?)
+      else
+        # chunk input in 6-word sentences
+        read_input_by_6_words do |arr|
+          yield Sixword.decode(arr, padding_ok: pad?)
+        end
       end
     end
 
@@ -157,7 +177,16 @@ module Sixword
         raise ArgumentError.new("block is required")
       end
 
-      if hex_style
+      if hex_style == "base64" || hex_style == "b64"
+        # Base64 needs 10.66 bytes to encode 8 binary bytes
+        # so we can't neatly chunk input like we can with hex.
+        # Instead just read the whole thing and yield in chunks of 8 bytes.
+        buf = Base64.decode64(stream.read)
+        buf.each_char.each_slice(8) do |chunk|
+          yield chunk.join
+        end
+
+      elsif hex_style
         # yield data in chunks from accumulate_hex_input until EOF
         accumulate_hex_input do |hex|
           begin
@@ -169,6 +198,7 @@ module Sixword
             yield data
           end
         end
+
       else
         # yield data 8 bytes at a time until EOF
         while true
@@ -219,8 +249,9 @@ module Sixword
       case hex_style
       when 'lower', 'lowercase'
       when 'finger', 'fingerprint'
+      when 'colon', 'colons'
       else
-        raise CLIError.new("unknown hex style: #{hex_style.inspect}")
+        raise CLIError.new("unknown style: #{hex_style.inspect}")
       end
 
       while true

data/lib/sixword/version.rb

@@ -1,4 +1,4 @@
 module Sixword
   # version string
-  VERSION = '0.4.0'.freeze
+  VERSION = '0.5.0'.freeze
 end

data/sixword.gemspec

@@ -8,13 +8,14 @@ Gem::Specification.new do |spec|
   spec.version       = Sixword::VERSION
   spec.authors       = ['Andy Brody']
   spec.email         = ['git@abrody.com']
-  spec.summary       = 'Implementation of RFC 2289 compatible 6-word encoding'
+  spec.summary       = 'Encode binary data for humans (RFC 2289 compatible 6-word encoding)'
   spec.description   = <<-EOM
-    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
+    Sixword encodes binary data in a human-friendly format using English words.
+    It uses the 6-word binary encoding created for S/Key (tm) and standardized
+    by RFC 2289, RFC 1760, and RFC 1751. Binary data is encoded using a
+    dictionary of 2048 short English words (1-4 letters in length). Each block
+    of 64 bits is encoded using 6 words, which includes 2 parity bits for error
+    checking. This is ideal for transmitting binary data such as cryptographic
     keys where humans must communicate or enter the values.
 
     See also: Bubble Babble, PGP Word List, Diceware, Base64, Base32
@@ -34,5 +35,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop', '~> 0.49'
   spec.add_development_dependency 'yard'
 
-  spec.required_ruby_version = '>= 1.9.3'
+  spec.add_dependency 'base64'
+
+  spec.required_ruby_version = '>= 3.0'
 end

data/spec/cli/cli_spec.rb

@@ -80,7 +80,7 @@ RSpec.describe Sixword::CLI do
   end
 
   it 'returns expected error codes in various conditions' do
-    run_sixword(%w{-e --hex-style nonexistent}, '', /unknown hex style/, 2)
+    run_sixword(%w{-e --hex-style nonexistent}, '', /unknown style/, 2)
     run_sixword(['-d'], "BEAK NET SITE ROTH SWIM FOR\n", /Parity bits do not match/, 3)
     run_sixword(['-d'], "ZZZ A A A A A\n", /Unknown word: "ZZZ"/, 4)
     run_sixword(['-d'], "AAAAAA A A A A A\n", /1-4 chars/, 5)
@@ -100,14 +100,35 @@ RSpec.describe Sixword::CLI do
 
   it 'handles basic hex styles' do
     run_sixword(['-H'], "54:65:73:74:69:6e:67:0a\n", "BEAK NET SITE ROTH SWIM FORM\n")
+    run_sixword(%w{-e -S colons}, "54:65:73:74:69:6e:67:0a\n", "BEAK NET SITE ROTH SWIM FORM\n")
     run_sixword(['-H'], "54657374696e670a\n", "BEAK NET SITE ROTH SWIM FORM\n")
     run_sixword(['-H'], "5465 7374 696E 670A\n", "BEAK NET SITE ROTH SWIM FORM\n")
+    run_sixword(%w{-S lower}, "54657374696e670a\n", "BEAK NET SITE ROTH SWIM FORM\n")
 
     run_sixword(['-dH'], "BEAK NET SITE ROTH SWIM FORM\n", "54657374696e670a\n")
     run_sixword(['-df'], "BEAK NET SITE ROTH SWIM FORM\n", "5465 7374 696E 670A\n")
     run_sixword(%w{-d -S colons}, "BEAK NET SITE ROTH SWIM FORM\n", "54:65:73:74:69:6e:67:0a\n")
   end
 
+  it 'handles base64' do
+    run_sixword(['--base64'], "VGVzdGluZwo=\n", "BEAK NET SITE ROTH SWIM FORM\n")
+    run_sixword(%w{-d --base64}, "BEAK NET SITE ROTH SWIM FORM\n", "VGVzdGluZwo=\n")
+    run_sixword(%w{-d -S base64}, "BEAK NET SITE ROTH SWIM FORM\n", "VGVzdGluZwo=\n")
+  end
+
+  it 'handles long base64' do
+    run_sixword(
+      %w{--base64},
+      "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1w",
+      "BEAK US ACHE SOUR BERN LOLA\nCORE ARC HULK SLID DREW DUE\nCHUB ENDS BOG RUSS BESS MAST\n"
+    )
+    run_sixword(
+      %w{-d --base64},
+      "BEAK US ACHE SOUR BERN LOLA\nCORE ARC HULK SLID DREW DUE\nCHUB ENDS BOG RUSS BESS MAST\n",
+      "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1w\n"
+    )
+  end
+
   it 'should encode/decode RFC hex vectors correctly' do
     Sixword::TestVectors::HexTests.each do |_section, tests|
       tests.each do |hex, sentence|

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sixword
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Andy Brody
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -94,12 +93,27 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |2
-      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
+      Sixword encodes binary data in a human-friendly format using English words.
+      It uses the 6-word binary encoding created for S/Key (tm) and standardized
+      by RFC 2289, RFC 1760, and RFC 1751. Binary data is encoded using a
+      dictionary of 2048 short English words (1-4 letters in length). Each block
+      of 64 bits is encoded using 6 words, which includes 2 parity bits for error
+      checking. This is ideal for transmitting binary data such as cryptographic
       keys where humans must communicate or enter the values.
 
       See also: Bubble Babble, PGP Word List, Diceware, Base64, Base32
@@ -138,7 +152,6 @@ homepage: https://github.com/ab/sixword
 licenses:
 - GPL-3
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -146,17 +159,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.9.3
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Implementation of RFC 2289 compatible 6-word encoding
+summary: Encode binary data for humans (RFC 2289 compatible 6-word encoding)
 test_files:
 - spec/cli/cli_spec.rb
 - spec/spec_helper.rb