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.
Base64EncodedBufferSize(size_t message_size)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.
PrefixedBase64Encode(std::span<const std::byte> binary_message,std::span<char> output_buffer)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.
PrefixedBase64Encode(std::span<const uint8_t> binary_message,std::span<char> output_buffer)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.
PrefixedBase64Decode(std::string_view base64_message,std::span<std::byte> output_buffer)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.
PrefixedBase64DecodeInPlace(std::span<std::byte> buffer)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
130