Jean-Pierre Moreau. jpm-phys@iquebec.com, 2004-05-05.

Program with source in C for base 32 encoding of a binary octet stream:

  base32encoding/BinaryToBase32enc.c  (version 2003-07-05)

Contents of this README

 - Manifest (list of files)
 - License (not really needed)
 - Implements an IETF draft proposed Base 32 standard
 - Compiling BinaryToBaSE32enc.c
 - Usage
 - Example, get a file SHA-1 digest in base32 encoding
 - Example of a sh/bash executable script based on above sha1 to base 32
 - Algorithm of base 32 encoding of this BinaryToBase32enc.c.

Manifest

 - base32encoding/README
     this file
 - base32encoding/draft-josefsson-base-encoding-04.txt
     the IETF draft for this program base 32 encoding; see below URL.
 - base32encoding/BinaryToBase32enc.c
     the C source code

License

  Small piece of code; similar probably included in many softwares, so
  no need for a real license.

  For it, I want BSD style open source license. I just NOT want some entity
  taking this code to block others from using it freely (as in free speech
  and as in free beer).

  Not for this one, but I am somewhat paranoiac about some entities, and
  would use a GPL style license for larger projects.

Implements an IETF draft proposed Base 32 standard

  The (not yet standard?):

    IETF draft "draft-josefsson-base-encoding-04.txt":
    Internet-Draft           February 2002        Expires: August 2, 2002
    Base Encoding of Data    draft-josefsson-base-encoding-04

  For example found 2003-07 on the Internet at
    http://www.ietf.org/internet-drafts/draft-josefsson-base-encoding-04.txt
  And this file is included here.

Compiling BinaryToBaSE32enc.c

   Simple compilation. In my GNU/Linux Slackware system with GNU C compiler:
     $ gcc -o bin2encod32 BinaryToBase32enc.c
   ('bin2encod32' stands for 'binary to encoding base 32'.)

Usage

  - input from stdin: any number of binary octets (nOctetsIn = 0, 1, ...)
    (bytes of 8 bits = octet);
  - output to stdout: characters 'highly' printable, case insensitive,
    ( (8 * nOctetsIn)/5 + possible padding) characters, coded input of
    5 bits per output character. All Upper case for alphabetical characters.
    Padding (with '=' char) following proposed standard base 32 encoding.

Example, get a file SHA-1 digest in base32 encoding.

   Sha-1 base 32 digest given by some servant for the Gnutella P2P protocol.

   Example using openssl to compute sha-1, and convert to base32 encoding:
      $ openssl sha1 -binary fileToGetSha1 | BinaryToBase32enc ; echo
   For more on digests and options of openssl:
      $ man openssl}, \qt{$ openssl list-message-digest-commands
   Above works for my ($ openssl version #> OpenSSL 0.9.7d 17 Mar 2004).

Example of a sh/bash executable script based on above sha1 to base 32

   My executable file bin/sha1base32  (change to your path .../bin2encod32):

      #!/bin/sh
      # bin2encod32 is my base32encoding/BinaryToBase32enc.c executable
      if [ $# -ne 1 ] ; then
         echo "Usage: thisProg filename";
         exit;
      fi
      # "${1}" for some problematic filenames (spaces, special chars)
      openssl sha1 -binary "${1}" \
       | /home/jpmoreau/bin/bin2encod32 ; echo

Algorithm of base 32 encoding of this BinaryToBase32enc.c.

   Calling it an algorithm is somewhat exxagereted. It is more like a
   detailed explanation of the working of the code, based on the proposed
   IETF standard cited above. I needed it myself to be pretty sure of
   correctness of the code.

   The comments in source program have more detailed explanations.

   Algorithm for one complete quantum, 5 input octets.

   The algorithm for a quantum of 5 octets of input (see comments in the
   C program for algorithm with any number of bytes and required padding),
   here to show the conversion of 5 octets of 8 bits to 8 nibbles of 5 bits,
   i.e. example of encoding a quantum of 40 bits :

                       octet0  octet1  octet2  octet3  octet4
                      <------><------><------><------><------>

      hex          :     3   c   0   b   3   6   b   7   9   e
      binary       :  0011110000001011001101101011011110011110
      5 bits value :      7   16    5   19   13   13   28   30
      encoding     :      H    Q    F    T    N    N    4    6

                      <---><---><---><---><---><---><---><--->
                       nib0 nib1 nib2 nib3 nib4 nib5 nib6 nib7

   Numbering of bits I use in an octet or a nibble of 5 bits here:

    bit 0 is first at left so is Most Significant Bit,
    so bit 7 is last and least significant bit of an octet,
    and bit 4 is last and least significant bit of a nibble of 5 bits.

  1st input octet, octet0 :
     nibble0 = 5 left bits of octet0
     nibble1(bits 0 to 2) = 3 right bits of octet0

  2nd input octet, octet1 :
     nibble1(bits 3,4) = 2 left bits of octet1 = bits 0 and 1 of octet1
     nibble2           = bits 2 to 6 of octet1
     nibble3(bit 0)    = bit 7 of octet1 = last bit of octet1

  3rd input octet, octet2 :
     nibble3(bits 1 to 4) = 4 left bits of octet2
     nibble4(bits 0 to 3) = 4 right bits of octet2

  4th input octet, octet3 :
     nibble4(bit 4) = 1st left bit of octet3 = bit 0 of octet3
     nibble5 = bits 1 to 5 of octet3
     nibble6(bits 0,1) = bits 6,7 of octet3 = last 2 bits of octet3

  5th input octet, octet4 :
     nibble6(bits 2 to 4) = 3 left bits of octet4
     nibble7 = 5 right bits of octet4