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