third_party/pigweed/repo/pw_tokenizer/public/pw_tokenizer/base64.h

   1 // Copyright 2020 The Pigweed Authors
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
   4 // use this file except in compliance with the License. You may obtain a copy of
   5 // the License at
   6 //
   7 //     https://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  12 // License for the specific language governing permissions and limitations under
  13 // the License.
  14
  15 // This file provides functions for working with the prefixed Base64 format for
  16 // tokenized messages. This format is useful for transmitting tokenized messages
  17 // as plain text.
  18 //
  19 // The format uses a prefix character ($), followed by the Base64 version of the
  20 // tokenized message. For example, consider a tokenized message with token
  21 // 0xfeb35a42 and encoded argument 0x13. This messsage would be encoded as
  22 // follows:
  23 //
  24 //            Binary: 42 5a b3 fe 13  [5 bytes]
  25 //
  26 //   Prefixed Base64: $Qlqz/hM=       [9 bytes]
  27 //
  28 #pragma once
  29
  30 #include <stddef.h>
  31
  32 #include "pw_preprocessor/util.h"
  33
  34 // This character is used to mark the start of a Base64-encoded tokenized
  35 // message. For consistency, it is recommended to always use $ if possible.
  36 // If required, a different non-Base64 character may be used as a prefix.
  37 #define PW_TOKENIZER_BASE64_PREFIX '$'
  38
  39 PW_EXTERN_C_START
  40
  41 // Encodes a binary tokenized message as prefixed Base64 with a null terminator.
  42 // Returns the encoded string length (excluding the null terminator). Returns 0
  43 // if the buffer is too small. Always null terminates if the output buffer is
  44 // not empty.
  45 //
  46 // Equivalent to pw::tokenizer::PrefixedBase64Encode.
  47 size_t pw_tokenizer_PrefixedBase64Encode(const void* binary_message,
  48                                          size_t binary_size_bytes,
  49                                          void* output_buffer,
  50                                          size_t output_buffer_size_bytes);
  51
  52 // Decodes a prefixed Base64 tokenized message to binary. Returns the size of
  53 // the decoded binary data. The resulting data is ready to be passed to
  54 // pw::tokenizer::Detokenizer::Detokenize. Returns 0 if the buffer is too small,
  55 // the expected prefix character is missing, or the Base64 data is corrupt.
  56 //
  57 // Equivalent to pw::tokenizer::PrefixedBase64Encode.
  58 size_t pw_tokenizer_PrefixedBase64Decode(const void* base64_message,
  59                                          size_t base64_size_bytes,
  60                                          void* output_buffer,
  61                                          size_t output_buffer_size);
  62
  63 PW_EXTERN_C_END
  64
  65 #ifdef __cplusplus
  66
  67 #include <span>
  68 #include <string_view>
  69
  70 #include "pw_base64/base64.h"
  71 #include "pw_tokenizer/config.h"
  72 #include "pw_tokenizer/tokenize.h"
  73
  74 namespace pw::tokenizer {
  75
  76 inline constexpr char kBase64Prefix = PW_TOKENIZER_BASE64_PREFIX;
  77
  78 // Returns the size of a tokenized message (token + arguments) when encoded as
  79 // prefixed Base64. This can be used to size a buffer for encoding. Includes
  80 // room for the prefix character ($), encoded message, and a null terminator.
  81 constexpr size_t Base64EncodedBufferSize(size_t message_size) {
  82   return sizeof(kBase64Prefix) + base64::EncodedSize(message_size) +
  83          sizeof('\0');
  84 }
  85
  86 // The minimum buffer size that can hold a tokenized message that is
  87 // PW_TOKENIZER_CFG_ENCODING_BUFFER_SIZE_BYTES long encoded as prefixed Base64.
  88 inline constexpr size_t kDefaultBase64EncodedBufferSize =
  89     Base64EncodedBufferSize(PW_TOKENIZER_CFG_ENCODING_BUFFER_SIZE_BYTES);
  90
  91 // Encodes a binary tokenized message as prefixed Base64 with a null terminator.
  92 // Returns the encoded string length (excluding the null terminator). Returns 0
  93 // if the buffer is too small. Always null terminates if the output buffer is
  94 // not empty.
  95 inline size_t PrefixedBase64Encode(std::span<const std::byte> binary_message,
  96                                    std::span<char> output_buffer) {
  97   return pw_tokenizer_PrefixedBase64Encode(binary_message.data(),
  98                                            binary_message.size(),
  99                                            output_buffer.data(),
 100                                            output_buffer.size());
 101 }
 102
 103 // Also accept a std::span<const uint8_t> for the binary message.
 104 inline size_t PrefixedBase64Encode(std::span<const uint8_t> binary_message,
 105                                    std::span<char> output_buffer) {
 106   return PrefixedBase64Encode(std::as_bytes(binary_message), output_buffer);
 107 }
 108
 109 // Decodes a prefixed Base64 tokenized message to binary. Returns the size of
 110 // the decoded binary data. The resulting data is ready to be passed to
 111 // pw::tokenizer::Detokenizer::Detokenize.
 112 inline size_t PrefixedBase64Decode(std::string_view base64_message,
 113                                    std::span<std::byte> output_buffer) {
 114   return pw_tokenizer_PrefixedBase64Decode(base64_message.data(),
 115                                            base64_message.size(),
 116                                            output_buffer.data(),
 117                                            output_buffer.size());
 118 }
 119
 120 // Decodes a prefixed Base64 tokenized message to binary in place. Returns the
 121 // size of the decoded binary data.
 122 inline size_t PrefixedBase64DecodeInPlace(std::span<std::byte> buffer) {
 123   return pw_tokenizer_PrefixedBase64Decode(
 124       buffer.data(), buffer.size(), buffer.data(), buffer.size());
 125 }
 126
 127 }  // namespace pw::tokenizer
 128
 129 #endif  // __cplusplus