ucw/doc/basecode.txt

   1 Base64 and Base224 encodings
   2 ============================
   3
   4 These modules can be used to encode and decode data to and from
   5 base64 (described in RFC 3548) and base224 (not described in any
   6 standard, uses all non-control characters of ASCII).
   7
   8 - <<base64,Base64>>
   9 - <<base224,Base224>>
  10 - <<usage,Usage>>
  11 - <<basecode,The basecode utility>>
  12
  13 [[base64]]
  14 ucw/base64.h
  15 ------------
  16 !!ucw/base64.h
  17
  18 [[base224]]
  19 ucw/base224.h
  20 -------------
  21 !!ucw/base224.h
  22
  23 [[usage]]
  24 Usage
  25 -----
  26
  27 - You may want to encode small block of known size. Just allocate the
  28   output buffer and feed the data to the function.
  29
  30   byte output[BASE64_ENC_LENGTH(input_size)];
  31   uns output_size = base64_encode(output, input, input_size);
  32
  33 - Decoding can be done in similar way. It is enough to have output
  34   buffer of the same size as the input one.
  35
  36 - Encoding of a stream of unknown or large size can be split into
  37   chunks. The input chunk size must be multiple of `BASE64_IN_CHUNK`.
  38   The output will be corresponding multiple of `BASE64_OUT_CHUNK`.
  39
  40   uns input_size;
  41   byte input[BASE64_IN_CHUNK * 10];
  42   while(input_size = read_chunk(input, BASE64_IN_CHUNK * 10)) {
  43     byte output[BASE64_OUT_CHUNK * 10];
  44     uns output_size = base64_encode(output, input, input_size);
  45     use_chunk(output, output_size);
  46   }
  47
  48 - Decoding of a stream is done in the same way, just swap
  49   `BASE64_IN_CHUNK` and `BASE64_OUT_CHUNK` (you feed the decode
  50   function with `BASE64_OUT_CHUNK` multiple and get `BASE64_IN_CHUNK`
  51   multiple).
  52
  53 The base224 has similar interface, therefore you can use it the same
  54 way as base64.
  55
  56 [[basecode]]
  57 The basecode utility
  58 --------------------
  59 You can use the encoding/decoding routines from command line, trough
  60 `basecode` command. You have to specify the operation by a command
  61 line argument and give it the data on standard input. The arguments
  62 are:
  63
  64 - `-e`: Encode to base64.
  65 - `-d`: Decode from base64.
  66 - `-E`: Encode to base224.
  67 - `-D`: Decode from base224.
  68
  69 Furthermore, you can provide `--prefix` argument. If you do, the
  70 output (when encoding) will be split to lines by default number of
  71 chunks and the value of prefix will be prepended to each of them.
  72 When decoding, it removes the prefix from the beginning of line.
  73
  74 You can override the default number of blocks for line-splitting by
  75 `--blocks` argument.