base64
======

"base64" is a potentially useful tutorial program written mostly in native C,
but also using some intrinsic C++ definitions, such as "bool".


Illustrates the use of:
-----------------------
typedef
macro's
bit shifting
bit masks
bit comparisons
ternary conditions
pointer arithmetic
type casting

The program runs as a stand-alone Base64 encoder and decoder console
application, but could easily be modified to be used as a callable module.
Refer either to the Microsoft Windows(tm) or Unix/Linux sections below for
directions regarding compiling the source modules if you choose to do so.

======================
Microsoft Windows Only
======================

Extract the base64 files:
-------------------------
pkunzip base64.zip

This will produce:
base64.exe      - The base64 binary executable.
base64.cpp      - The base64 source code.
base64.mak      - The Makefile to build the base64.exe binary executable.
readme.txt      - This file.

(You obviously already know how to extract a zip file
if you're reading this!)

To recompile base64:
--------------------
nmake /f base64.mak CFG="Release" CLEAN	
nmake /f base64.mak CFG="Release"

or

nmake /f base64.mak CFG="Debug" CLEAN
nmake /f base64.mak CFG="Debug"

Note: The latter nmake commands will either build a debugging version of
      base64.exe in a directory named ".\Debug" or a release version of
      base64.exe in a directory named ".\Release".  If you omit the CFG=
      parameter, it will default to "Release".

=================================
End of Microsoft Windows(tm) Only
=================================

===============
UNIX/Linux Only
===============

Extract the base64 files:
-------------------------
gunzip -c base64.tar.gz | tar -xvf -

This will produce:
base64          - The base64 binary executable.
base64.cpp      - The base64 source code.
Makefile        - The Makefile to build the base64 binary.
README          - This file.

(You obviously already know how to uncompress and extract a "tarball"
if you're reading this!)

To recompile base64:
--------------------
make clean
make

or

make clean
make CFG=debug

Note: The latter make commands will either build a debugging version of base64
      or a release version of base64.

======================
End of UNIX/Linux Only
======================

Overview:
---------
Base64 is a simple encryption technique often used on the Internet for simple
User-ID and password authentication.  Since it is a reversable encryption
technique, it is certainly not considered strong encryption.

Base64 processes a string by octets (3 Byte blocks).  For every octet in the
decoded string, four byte blocks are generated in the encoded string.  If the
decoded string length is not a multiple of 3, the Base64 algorithm pads the
end of the encoded string with equal signs '='.

An example taken from RFC 2617 (HTTP Authentication):
-----------------------------------------------------
If a protected Resource (URL) requires basic authentication
(Authorization: Basic) for access, a valid Base64 encoded User-ID and
Password must be supplied in the HTTP request header, otherwise a
"HTTP 401 Unauthorized" response is returned.

Example:

User-ID:Password string  = "Aladdin:open sesame"
Base64 encoded   string  = "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

The above example User-ID and Password could be provided in the HTTP request
header as follows:

GET /someresource.html HTTP/1.1<CR><NL>
Host: www.somedomaine.com<CR><NL>
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==<CR><NL>
<CR><NL>
 


Usage:   base64 OPTION [STRING]
-------------------------------

OPTION:  -h Displays a brief messages.
         -e Base64 encode the 7-Bit ASCII STRING.
         -d Decode the Base64 STRING to 7-Bit ASCII.

STRING:  Either a 7-Bit ASCII text string for encoding or a Base64
         encoded string for decoding back to 7-Bit ASCII.

Note:    For EBCDIC and other collating sequences, the STRING must first
         be converted to 7-Bit ASCII before passing it to this module and
         the return string must be converted back to the appropriate
         collating sequence.

Example:
--------

$ ./base64 -e "Aladdin:open sesame"

Base64 Encoder/Decoder

Decoded string length = 19
Decoded string        = "Aladdin:open sesame"
Encoded buffer size   = 29
Encoded string length = 28
Encoded string        = "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
Base64 encoding complete.

$ ./base64 -d "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

Base64 Encoder/Decoder

Encoded string length = 28
Encoded string        = "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
Decoded buffer size   = 22
Decoded string length = 19
Decoded string        = "Aladdin:open sesame"
Base64 decoding complete.

$

Distribution and use:
---------------------
This software may be freely used and distributed as long as the author is
credited where ever it is used or distributed, including, but not limited to,
educational facilities.


Copyright (c) 1994 - 2001
Marc Niegowski
Connectivity, Inc.
All rights reserved.
