mirror of
https://github.com/transmission/transmission
synced 2024-12-23 00:04:06 +00:00
b928ae1ba8
Some crypto libraries (like CyaSSL, MatrixSSL and CommonCrypto) either don't have or expose this functionality at all, expose only part of it, or (like OpenSSL) have heavyweight API for it. Also, for the task as easy as BASE64 encoding and decoding it's much better to use small and simple specialized library.
143 lines
4.9 KiB
Text
143 lines
4.9 KiB
Text
b64: Base64 Encoding/Decoding Routines
|
|
======================================
|
|
|
|
Overview:
|
|
--------
|
|
libb64 is a library of ANSI C routines for fast encoding/decoding data into and
|
|
from a base64-encoded format. C++ wrappers are included, as well as the source
|
|
code for standalone encoding and decoding executables.
|
|
|
|
base64 consists of ASCII text, and is therefore a useful encoding for storing
|
|
binary data in a text file, such as xml, or sending binary data over text-only
|
|
email.
|
|
|
|
References:
|
|
----------
|
|
* Wikipedia article:
|
|
http://en.wikipedia.org/wiki/Base64
|
|
* base64, another implementation of a commandline en/decoder:
|
|
http://www.fourmilab.ch/webtools/base64/
|
|
|
|
Why?
|
|
---
|
|
I did this because I need an implementation of base64 encoding and decoding,
|
|
without any licensing problems. Most OS implementations are released under
|
|
either the GNU/GPL, or a BSD-variant, which is not what I require.
|
|
|
|
Also, the chance to actually use the co-routine implementation in code is rare,
|
|
and its use here is fitting. I couldn't pass up the chance.
|
|
For more information on this technique, see "Coroutines in C", by Simon Tatham,
|
|
which can be found online here:
|
|
http://www.chiark.greenend.org.uk/~sgtatham/coroutines.html
|
|
|
|
So then, under which license do I release this code? On to the next section...
|
|
|
|
License:
|
|
-------
|
|
This work is released under into the Public Domain.
|
|
It basically boils down to this: I put this work in the public domain, and you
|
|
can take it and do whatever you want with it.
|
|
|
|
An example of this "license" is the Creative Commons Public Domain License, a
|
|
copy of which can be found in the LICENSE file, and also online at
|
|
http://creativecommons.org/licenses/publicdomain/
|
|
|
|
Commandline Use:
|
|
---------------
|
|
There is a new executable available, it is simply called base64.
|
|
It can encode and decode files, as instructed by the user.
|
|
|
|
To encode a file:
|
|
$ ./base64 -e filea fileb
|
|
fileb will now be the base64-encoded version of filea.
|
|
|
|
To decode a file:
|
|
$ ./base64 -d fileb filec
|
|
filec will now be identical to filea.
|
|
|
|
Programming:
|
|
-----------
|
|
Some C++ wrappers are provided as well, so you don't have to get your hands
|
|
dirty. Encoding from standard input to standard output is as simple as
|
|
|
|
#include <b64/encode.h>
|
|
#include <iostream>
|
|
int main()
|
|
{
|
|
base64::encoder E;
|
|
E.encode(std::cin, std::cout);
|
|
return 0;
|
|
}
|
|
|
|
Both standalone executables and a static library is provided in the package,
|
|
|
|
Example code:
|
|
------------
|
|
The 'examples' directory contains some simple example C code, that demonstrates
|
|
how to use the C interface of the library.
|
|
|
|
Implementation:
|
|
--------------
|
|
It is DAMN fast, if I may say so myself. The C code uses a little trick which
|
|
has been used to implement coroutines, of which one can say that this
|
|
implementation is an example.
|
|
|
|
(To see how the libb64 codebase compares with some other BASE64 implementations
|
|
available, see the BENCHMARKS file)
|
|
|
|
The trick involves the fact that a switch-statement may legally cross into
|
|
sub-blocks. A very thorough and enlightening essay on co-routines in C, using
|
|
this method, can be found in the above mentioned "Coroutines in C", by Simon
|
|
Tatham: http://www.chiark.greenend.org.uk/~sgtatham/coroutines.html
|
|
|
|
For example, an RLE decompressing routine, adapted from the article:
|
|
1 static int STATE = 0;
|
|
2 static int len, c;
|
|
3 switch (STATE)
|
|
4 {
|
|
5 while (1)
|
|
6 {
|
|
7 c = getchar();
|
|
8 if (c == EOF) return EOF;
|
|
9 if (c == 0xFF) {
|
|
10 len = getchar();
|
|
11 c = getchar();
|
|
12 while (len--)
|
|
13 {
|
|
14 STATE = 0;
|
|
15 return c;
|
|
16 case 0:
|
|
17 }
|
|
18 } else
|
|
19 STATE = 1;
|
|
20 return c;
|
|
21 case 1:
|
|
22 }
|
|
23 }
|
|
24 }
|
|
|
|
As can be seen from this example, a coroutine depends on a state variable,
|
|
which it sets directly before exiting (lines 14 and 119). The next time the
|
|
routine is entered, the switch moves control to the specific point directly
|
|
after the previous exit (lines 16 and 21).hands
|
|
|
|
(As an aside, in the mentioned article the combination of the top-level switch,
|
|
the various setting of the state, the return of a value, and the labelling of
|
|
the exit point is wrapped in #define macros, making the structure of the
|
|
routine even clearer.)
|
|
|
|
The obvious problem with any such routine is the static keyword.
|
|
Any static variables in a function spell doom for multithreaded applications.
|
|
Also, in situations where this coroutine is used by more than one other
|
|
coroutines, the consistency is disturbed.
|
|
|
|
What is needed is a structure for storing these variabled, which is passed to
|
|
the routine seperately. This obviously breaks the modularity of the function,
|
|
since now the caller has to worry about and care for the internal state of the
|
|
routine (the callee). This allows for a fast, multithreading-enabled
|
|
implementation, which may (obviously) be wrapped in a C++ object for ease of
|
|
use.
|
|
|
|
The base64 encoding and decoding functionality in this package is implemented
|
|
in exactly this way, providing both a high-speed high-maintanence C interface,
|
|
and a wrapped C++ which is low-maintanence and only slightly less performant.
|