From 4a65d555b1d57bc037b7fef9d04a611c43a44d86 Mon Sep 17 00:00:00 2001 From: Michal Vaner Date: Thu, 11 Sep 2008 14:28:31 +0200 Subject: [PATCH] ucw docs: base64 & base224 Documentation of base64 and base224 encoding. Describes the basecode utility as well. --- ucw/base224.h | 21 ++++++++++--- ucw/base64.h | 18 ++++++++--- ucw/doc/Makefile | 2 +- ucw/doc/basecode.txt | 75 ++++++++++++++++++++++++++++++++++++++++++++ ucw/doc/index.txt | 1 + 5 files changed, 107 insertions(+), 10 deletions(-) create mode 100644 ucw/doc/basecode.txt diff --git a/ucw/base224.h b/ucw/base224.h index 7e815d8c..f1941919 100644 --- a/ucw/base224.h +++ b/ucw/base224.h @@ -7,12 +7,23 @@ * of the GNU Lesser General Public License. */ +/** + * Encodes @len bytes of data pointed to by @src by base224 encoding. + * Stores them in @dest and returns the number of bytes the output + * takes. + */ uns base224_encode(byte *dest, const byte *src, uns len); +/** + * Decodes @len bytes of data pointed to by @src from base224 encoding. + * All invalid characters are ignored. The result is stored into @dest + * and length of the result is returned. + */ uns base224_decode(byte *dest, const byte *src, uns len); -/* - * Warning: when encoding, at least 4 bytes of extra space are needed. - * Better use this macro to calculate buffer size. +/** + * Use this macro to calculate base224_encode() output buffer size. + * It can happen 4 more bytes would be needed, this macro takes care + * of that. */ #define BASE224_ENC_LENGTH(x) (((x)*8+38)/39*5) @@ -21,5 +32,5 @@ uns base224_decode(byte *dest, const byte *src, uns len); * always BASE224_OUT_CHUNK bytes long. If a longer block is split * to such chunks, the result will be identical. */ -#define BASE224_IN_CHUNK 39 -#define BASE224_OUT_CHUNK 40 +#define BASE224_IN_CHUNK 39 /** Chunk size on the un-encoded side. **/ +#define BASE224_OUT_CHUNK 40 /** Chunk size on the encoded side. **/ diff --git a/ucw/base64.h b/ucw/base64.h index 78909664..3f30b69a 100644 --- a/ucw/base64.h +++ b/ucw/base64.h @@ -7,11 +7,21 @@ * of the GNU Lesser General Public License. */ +/** + * Encodes @len bytes of data pointed to by @src by base64 encoding. + * Stores them in @dest and returns the number of bytes the output + * takes. + */ uns base64_encode(byte *dest, const byte *src, uns len); +/** + * Decodes @len bytes of data pointed to by @src from base64 encoding. + * All invalid characters are ignored. The result is stored into @dest + * and length of the result is returned. + */ uns base64_decode(byte *dest, const byte *src, uns len); -/* - * Use this macro to calculate buffer size. +/** + * Use this macro to calculate base64_encode() output buffer size. */ #define BASE64_ENC_LENGTH(x) (((x)+2)/3 *4) @@ -20,6 +30,6 @@ uns base64_decode(byte *dest, const byte *src, uns len); * always BASE64_OUT_CHUNK bytes long. If a longer block is split * to such chunks, the result will be identical. */ -#define BASE64_IN_CHUNK 3 -#define BASE64_OUT_CHUNK 4 +#define BASE64_IN_CHUNK 3 /** Size of chunk on the un-encoded side. **/ +#define BASE64_OUT_CHUNK 4 /** Size of chunk on the encoded side. **/ diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile index b25d4beb..3b9216ac 100644 --- a/ucw/doc/Makefile +++ b/ucw/doc/Makefile @@ -2,7 +2,7 @@ DIRS+=ucw/doc -UCW_DOCS=fastbuf index +UCW_DOCS=fastbuf index basecode UCW_INDEX=$(o)/ucw/doc/def_index.html $(UCW_INDEX): DOC_HEAD=$(s)/ucw/doc/def_index.txt diff --git a/ucw/doc/basecode.txt b/ucw/doc/basecode.txt new file mode 100644 index 00000000..94b4102e --- /dev/null +++ b/ucw/doc/basecode.txt @@ -0,0 +1,75 @@ +Base64 and Base224 encodings +============================ + +These modules can be used to encode and decode data to and from +base64 (described in RFC 3548) and base224 (not described in any +standard, uses all non-control characters of ASCII). + +- <> +- <> +- <> +- <> + +[[base64]] +ucw/base64.h +------------ +!!ucw/base64.h + +[[base224]] +ucw/base224.h +------------- +!!ucw/base224.h + +[[usage]] +Usage +----- + +- You may want to encode small block of known size. Just allocate the + output buffer and feed the data to the function. + + byte output[BASE64_ENC_LENGTH(input_size)]; + uns output_size = base64_encode(output, input, input_size); + +- Decoding can be done in similar way. It is enough to have output + buffer of the same size as the input one. + +- Encoding of a stream of unknown or large size can be split into + chunks. The input chunk size must be multiple of `BASE64_IN_CHUNK`. + The output will be corresponding multiple of `BASE64_OUT_CHUNK`. + + uns input_size; + byte input[BASE64_IN_CHUNK * 10]; + while(input_size = read_chunk(input, BASE64_IN_CHUNK * 10)) { + byte output[BASE64_OUT_CHUNK * 10]; + uns output_size = base64_encode(output, input, input_size); + use_chunk(output, output_size); + } + +- Decoding of a stream is done in the same way, just swap + `BASE64_IN_CHUNK` and `BASE64_OUT_CHUNK` (you feed the decode + function with `BASE64_OUT_CHUNK` multiple and get `BASE64_IN_CHUNK` + multiple). + +The base224 has similar interface, therefore you can use it the same +way as base64. + +[[basecode]] +The basecode utility +-------------------- +You can use the encoding/decoding routines from command line, trough +`basecode` command. You have to specify the operation by a command +line argument and give it the data on standard input. The arguments +are: + +- `-e`: Encode to base64. +- `-d`: Decode from base64. +- `-E`: Encode to base224. +- `-D`: Decode from base224. + +Furthermore, you can provide `--prefix` argument. If you do, the +output (when encoding) will be split to lines by default number of +chunks and the value of prefix will be prepended to each of them. +When decoding, it removes the prefix from the beginning of line. + +You can override the default number of blocks for line-splitting by +`--blocks` argument. diff --git a/ucw/doc/index.txt b/ucw/doc/index.txt index 122a2e8a..aeccb034 100644 --- a/ucw/doc/index.txt +++ b/ucw/doc/index.txt @@ -10,3 +10,4 @@ You can see list of <>. Modules ------- - <> +- <> -- 2.39.2