Header-only C++11 library to encode/decode base64, base64url, base32, base32hexand hex (a.k.a. base16) as specified in RFC 4648, plus Crockford's base32.
MIT licensed with consistent, flexible API. Supports raw pointers,std::string
and (templated) character vectors without unnecessary allocations.Cross-platform with measured decent performance and without compiler warnings.
The following are 30 code examples for showing how to use pyasn1.type.univ.OctetString.These examples are extracted from open source projects. You can vote up the ones you like or vote down the ones you don't like, and go to the original project or source file by following the links above each example. The MIME type application/Octet-stream is considered to be one of the popular multipurpose application files. Generally this type is used for identifying the data.
Since cppcodec is a header-only library, no extra build step is needed.Alternatively, you can install the headers and build extra tools/tests with CMake.
A number of codec variants exist for base64 and base32, defining different alphabetsor specifying the use of padding and line breaks in different ways. cppcodec is designedto let you make a conscious choice about which one you're using, see below for a list of variants.
cppcodec's approach is to implement encoding/decoding algorithms in different classes for namespacing (e.g. cppcodec::base64_rfc4648
), with classes and their associated header files named verbatim after the codec variants.
Here is an expected standard use of cppcodec:
(The prior example included 'baseXX_default_*.h' includes, these are not recommended anymore and may eventually get deprecated.)
Currently supported codec variants are:
base64_rfc4648
uses the PEM/MIME/UTF-7 alphabet, that is (in order)A-Z, a-z, 0-9 plus characters '+' and '/'. This is what's usually consideredthe 'standard base64' that you see everywhere and requires padding ('=') butno line breaks. Whitespace and other out-of-alphabet symbols are regarded asa parse error.base64_url
is the same as base64_rfc4648
(and defined in the same RFC)but uses '-' (minus) and '_' (underscore) as special characters instead of'+' and '/'. This is safe to use for URLs and file names. Padding with '=' isrequired, it will be generated when encoding to a string and regarded as aparse error if it's not present when decoding.base64_url_unpadded
variant is the same as base64_url
, but '=' paddingcharacters are optional. When encoding, no padding will be appended to theresulting string. Decoding accepts either padded or unpadded strings.All base32 variants encode 5 bits as one (8-bit) character, which results inan encoded length of roughly 160% (= 8/5). Their selling point is mainlycase-insensitive decoding, no special characters and alphabets that can becommunicated via phone.
base32_rfc4648
implements the popular, standardized variant defined inRFC 4648. It uses the full upper-case alphabet A-Z for the first 26 valuesand the digit characters 2-7 for the last ten. Padding with '=' is requiredand makes the encoded string a multiple of 8 characters. The codec acceptsno invalid symbols, so if you want to let the user enter base32 data thenconsider replacing numbers '0', '1' and '8' with 'O', 'I' and 'B' on input.base32_crockford
implements Crockford base32.It's less widely used than the RFC 4648 alphabet, but offers a more carefullypicked alphabet and also defines decoding similar characters 'I', 'i', 'L'l' as '1' plus 'O' and 'o' as '0' so no care is required for user input.Crockford base32 does not use '=' padding. Checksums are not implemented.Note that the specification is ambiguous about whether to pad bit quintets tothe left or to the right, i.e. whether the codec is a place-based single numberencoding system or a concatenative iterative stream encoder. This codec variantpicks the streaming interpretation and thus zero-pads on the right. (Seehttp://merrigrove.blogspot.ca/2014/04/what-heck-is-base64-encoding-really.htmlfor a detailed discussion of the issue.)base32_hex
is the logical extension of the hexadecimal alphabet, and alsospecified in RFC 4648. It uses the digit characters 0-9 for the first 10 valuesand the upper-case letters A-V for the remaining ones. The alphabet isconceptually simple, but contains all of the ambiguous number/letter pairs thatthe other variants try to avoid. It is also less suitable for verbaltransmission. Padding with '=' is required and makes the encoded string amultiple of 8 characters.hex_upper
outputs upper-case letters and accepts lower-case as well.This is an octet-streaming codec variant and for decoding, requires an evennumber of input symbols. In other words, don't try to decode (0x)'F',(0x)'10F' etc. with this variant, use a place-based single number codecinstead if you want to do this. Also, you are expected to prepend and removea '0x' prefix externally as it won't be generated when encoding / will berejected when decoding.hex_lower
outputs lower-case letters and accepts upper-case as well.Similar to hex_upper
, it's stream-based (no odd symbol lengths) and doesnot deal with '0x' prefixes.cppcodec aims to support a range of codecs using a shared template-based implementation.The focus is on a high-quality API that encourages correct use, includes error handling,and is easy to adopt into other codebases. As a header-only library, cppcodec canship implementations of several codecs and variants while only compiling the onesthat you actually use.
Good performance is a goal, but not the topmost priority. In theory, templates allowsto write generic code that is optimized for each specialization individually; however,in practice compilers still struggle to produce code that's as simple as ahand-written specialized function. On release builds, depending on the C++ compiler,cppcodec runs in between (approx.) 100% and 300% of time compared to 'regular' optimizedbase64 implementations. Both are beat by highly optimized implementations that usevector instructions (such as this) or buy betterperformance with larger pre-computed tables (such as Chrome's base64 implementation).Debug builds of cppcodec are slower by an order of magnitude due to the use of templatesand abstractions; make sure you use release or minimum-size builds in production.
All codecs expose the same API. In the below documentation, replace <codec>
with adefault alias such as base64
, base32
or hex
, or with the full namespace such ascppcodec::base64_rfc4648
or cppcodec::base32_crockford
.
For templated parameters T
and Result
, you can use e.g. std::vector<uint8_t>
,std::string
or anything that supports:
.data()
and .size()
for T
(read-only) template parameters,Result
template parameters, also .reserve(size_t)
, .resize(size_t)
and .push_back([uint8_t|char])
.It's possible to support types lacking these functions, consult the code directly if you need this.
Encode binary data into an encoded (base64/base32/hex) string.Won't throw by itself, but the result type might throw on .resize()
.
Encode binary data into pre-allocated memory with a buffer size of<codec>::encoded_size(binary_size)
or larger.
Returns the byte size of the encoded string excluding null termination,which is equal to <codec>::encoded_size(binary_size)
.
If encoded_buffer_size
is larger than required, a single null termination character ('0'
)is written after the last encoded character. The encoded_size()
function ensures that the requiredbuffer size is large enough to hold the padding required for the respective codec variant.Provide a buffer of size encoded_size() + 1
to make it a null-terminated C string.
Calls abort() if encoded_buffer_size
is insufficient. (That way, the function can remain noexcept
rather than throwing on an entirely avoidable error condition.)
Calculate the (exact) length of the encoded string based on binary size,excluding null termination but including padding (if specified by the codec variant).
Decode an encoded (base64/base32/hex) string into a binary buffer.
Throws a cppcodec::parse_error exception (inheriting from std::domain_error)if the input data does not conform to the codec variant specification.Also, the result type might throw on .resize()
.
Decode an encoded string into pre-allocated memory with a buffer size of<codec>::decoded_max_size(encoded_size)
or larger.
Returns the byte size of the decoded binary data, which is less or equal to<codec>::decoded_max_size(encoded_size)
.
Calls abort() if binary_buffer_size
is insufficient, for consistency with encode().Throws a cppcodec::parse_error exception (inheriting from std::domain_error)if the input data does not conform to the codec variant specification.
Calculate the maximum size of the decoded binary buffer based on the encoded string length.
If the codec variant does not allow padding or whitespace / line breaks,the maximum decoded size will be the exact decoded size.
If the codec variant allows padding or whitespace / line breaks, the actual decoded sizemight be smaller. If you're using the pre-allocated memory result call, make sure to takeits return value (the actual decoded size) into account.