StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
secure_binary.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This is the base for StormByte Suite libraries.
5 *
6 * StormByte original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte source in this repository.
20 * They do not cover other StormByte modules or any third-party material
21 * shipped with this repository (including everything under thirdparty/),
22 * which remains under its own license.
23 *
24 * Neither license grants any patent rights. Any patent licenses required
25 * to use this software or third-party components must be obtained separately
26 * from the patent holders.
27 *
28 * StormByte is distributed in the hope that it will be useful,
29 * but WITHOUT ANY WARRANTY; without even the implied warranty of
30 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
31 * GNU Lesser General Public License for more details.
32 *
33 * You should have received a copy of the GNU Lesser General Public License
34 * version 3 along with StormByte. If not, see
35 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
36 *
37 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
38 */
39
40
41#pragma once
42
44
45#include <cstddef>
46#include <initializer_list>
47#include <span>
48#include <string_view>
49#include <utility>
50#include <vector>
51
56namespace StormByte {
61 namespace Safe {
74 class STORMBYTE_PUBLIC SecureBinary final: public Binary {
75 public:
79 SecureBinary() noexcept;
80
86 SecureBinary(const ByteSize& count, std::byte value);
87
92 explicit SecureBinary(const ByteSize& count);
93
98 explicit SecureBinary(std::span<const std::byte> bytes);
99
106 SecureBinary(const std::byte* bytes, const ByteSize& count);
107
112 SecureBinary(std::initializer_list<std::byte> list);
113
118 explicit SecureBinary(std::string_view text);
119
124 explicit SecureBinary(const char* text);
125
130 STORMBYTE_FORCE_INLINE explicit SecureBinary(const std::vector<std::byte>& bytes): SecureBinary(std::span<const std::byte>(bytes.data(), bytes.size())) {}
131
136 STORMBYTE_FORCE_INLINE explicit SecureBinary(std::vector<std::byte>&& bytes): SecureBinary(std::span<const std::byte>(bytes.data(), bytes.size())) {
137 Wipe(std::span<std::byte>(bytes.data(), bytes.capacity()));
138 bytes.clear();
139 bytes.shrink_to_fit();
140 }
141
147 template<Type::ByteInputRange R>
148 explicit SecureBinary(const R& range);
149
155 template<Type::ByteInputRange R>
156 explicit SecureBinary(R&& range);
157
163
168 SecureBinary(SecureBinary&& other) noexcept;
169
173 ~SecureBinary() noexcept override;
174
180 SecureBinary& operator=(const SecureBinary& other);
181
187 SecureBinary& operator=(SecureBinary&& other) noexcept;
188
194 SecureBinary& operator=(std::initializer_list<std::byte> list);
195
199 explicit operator std::vector<std::byte>() const& = delete;
200
204 explicit operator std::vector<std::byte>() && = delete;
205
209 String HexDump() const = delete;
210
215 String HexDump(Size columns) const = delete;
216
217 protected:
222 void Discard(std::span<std::byte> bytes) noexcept override;
223
228 bool ConstantTimeCompare() const noexcept override;
229
234 void Acquire(std::span<std::byte> block) noexcept override;
235
240 void Release(std::span<std::byte> block) noexcept override;
241 };
242
243 template<Type::ByteInputRange R>
245 if constexpr (requires { std::size(range); })
246 reserve(ByteSize{std::size(range)});
247 for (auto&& byte : range)
248 push_back(static_cast<std::byte>(byte));
249 }
250
251 template<Type::ByteInputRange R>
253 using U = std::remove_cvref_t<R>;
255 Binary::operator=(std::move(static_cast<Binary&>(range)));
256 } else {
257 if constexpr (requires { std::size(range); })
258 reserve(ByteSize{std::size(range)});
259 for (auto&& byte : range)
260 push_back(static_cast<std::byte>(byte));
261 }
262 }
263 }
264}
Count of octets (uint64_t storage).
Definition byte_size.hxx:105
std::byte * data() noexcept
Mutable pointer to the first byte, or null when empty.
static void Wipe(std::span< std::byte > bytes) noexcept
Zero bytes.
void reserve(const ByteSize &new_cap)
Request capacity of at least new_cap bytes.
STORMBYTE_FORCE_INLINE std::span< std::byte > span() noexcept
Mutable view of the occupied bytes.
Definition binary.hxx:458
void push_back(std::byte value)
Append one byte.
ByteSize size() const noexcept
Occupied length in bytes.
Binary & operator=(const Binary &other)
Copy assign.
Binary() noexcept
Construct an empty sequence.
Binary for secrets: every byte it drops or releases is zeroed first.
Definition secure_binary.hxx:74
SecureBinary() noexcept
Construct an empty sequence.
bool ConstantTimeCompare() const noexcept override
Equality with this object never stops at the first difference.
void Discard(std::span< std::byte > bytes) noexcept override
Zero bytes.
SecureBinary(SecureBinary &&other) noexcept
Move construct.
void Release(std::span< std::byte > block) noexcept override
Unlock the pages of block once no other block on the same pages is locked.
STORMBYTE_FORCE_INLINE SecureBinary(std::vector< std::byte > &&bytes)
Copy bytes from a caller-owned vector, then zero and release it.
Definition secure_binary.hxx:136
void Acquire(std::span< std::byte > block) noexcept override
Best effort: lock the pages of block in memory so they are not written to swap.
~SecureBinary() noexcept override
Zero the whole block, then release it.
SecureBinary(const SecureBinary &other)
Copy construct.
String HexDump() const =delete
Not available: the dump would hold the secret in memory that is never wiped.
Owned UTF-8 text.
Definition string.hxx:113
Count of abstract units (uint64_t storage).
Definition size.hxx:107
Derived derives from Base (std::is_base_of).
Definition relations.hxx:156
Lvalue reference type (std::is_lvalue_reference).
Definition categories.hxx:97
Owned values that cross a DLL without the caller's CRT.
Root namespace of the StormByte suite.
Octet count. Defined in byte_size.hxx. Forwarded so Type::Numeral can name it.
STL namespace.
#define STORMBYTE_FORCE_INLINE
Definition platform.h:134
#define STORMBYTE_PUBLIC
Definition visibility.h:52