Base64.h

Go to the documentation of this file.

/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2026.  All rights reserved
 */
#ifndef _Stroika_Foundation_Cryptography_Base64_h_
#define _Stroika_Foundation_Cryptography_Base64_h_ 1
 
#include "Stroika/Foundation/StroikaPreComp.h"
 
#include <string>
#include <vector>
 
#include "Stroika/Foundation/Characters/String.h"
#include "Stroika/Foundation/Common/Common.h"
#include "Stroika/Foundation/Memory/BLOB.h"
#include "Stroika/Foundation/Streams/InputStream.h"
#include "Stroika/Foundation/Streams/OutputStream.h"
 
/**
 *  \file
 *
 * TODO:
 *
 *      @todo   EncodeBase64 should return STROIKA string, or BLOB - not std::string? Or maybe std::string
 *              best - but document why - cuz always ascii data so more compact?? No - not good reason cuz
 *              we can construct a SUBTYPE of String that takes advantage of it.
 *
 *      @todo   DecodeBase64() should have an overload taking BinaryInputStream, and EncodeBase64()
 *              should have an overload with BinaryOutputStream (keeping existing overloads).
 *
 *      @todo   Tons todo optimizing this implementation (to not use temporary objects and
 *              avoiding copying).
 *
 */
 
/**
 *  Base64 (RFC 4648, section 4): bytes as text, each character standing for 6 bits, and back.
 *
 *  VERY WEAK encryption (Cryptography's ReadMe.md): the bytes made opaque - to a parser, and to most readers - and kept intact
 *  through a channel that would mangle them (mail, JSON, XML, an HTTP header); but secret from no one who recognizes it.
 */
namespace Stroika::Foundation::Cryptography::Encoding::Algorithm::Base64 {
 
    Memory::BLOB Decode (span<const char> s);
    Memory::BLOB Decode (const string& s);
    Memory::BLOB Decode (const u8string& s);
    Memory::BLOB Decode (const Characters::String& s);
    void         Decode (const string& s, const Streams::OutputStream::Ptr<byte>& out);
 
    /**
     *  What Encode puts after each 76 characters: a line break (as MIME's base64 has), or - eNone_LB - nothing, so the whole on
     *  one line (as base64 in an HTTP header, JSON, or an XML value usually is)
     */
    enum class LineBreak : uint8_t {
        eLF_LB,
        eCRLF_LB,
        eNone_LB,
        eAuto_LB = eCRLF_LB
    };
    struct Options {
        LineBreak fLineBreak{LineBreak::eAuto_LB};
    };
 
    /**
     *  \note BLOB overload redundant, but provided since slight performance tweak (@todo maybe replace with span<byte> for that case/reason)
     */
    string Encode (const Streams::InputStream::Ptr<byte>& from, const Options& o = {});
    string Encode (const Memory::BLOB& from, const Options& o = {});
 
}
 
namespace Stroika::Foundation::Cryptography::Encoding::Algorithm {
 
    [[deprecated ("Since Stroika v3.0d5 use Base64::Decode")]] inline Memory::BLOB DecodeBase64 (span<const char> s)
    {
        return Base64::Decode (s);
    }
    [[deprecated ("Since Stroika v3.0d5 use Base64::Decode")]] inline Memory::BLOB DecodeBase64 (const string& s)
    {
        return Base64::Decode (s);
    }
    [[deprecated ("Since Stroika v3.0d5 use Base64::Decode")]] inline Memory::BLOB DecodeBase64 (const u8string& s)
    {
        return Base64::Decode (s);
    }
    [[deprecated ("Since Stroika v3.0d5 use Base64::Decode")]] inline Memory::BLOB DecodeBase64 (const Characters::String& s)
    {
        return Base64::Decode (s);
    }
    [[deprecated ("Since Stroika v3.0d5 use Base64::Decode")]] inline void DecodeBase64 (const string& s, const Streams::OutputStream::Ptr<byte>& out)
    {
        Base64::Decode (s, out);
    }
 
    using Base64::LineBreak; // deprecated
    [[deprecated ("Since Stroika v3.0d5 use Base64::Encode")]] inline string EncodeBase64 (const Streams::InputStream::Ptr<byte>& from,
                                                                                           LineBreak lb = LineBreak::eAuto_LB)
    {
        return Base64::Encode (from, Base64::Options{.fLineBreak = lb});
    }
    [[deprecated ("Since Stroika v3.0d5 use Base64::Encode")]] inline string EncodeBase64 (const Memory::BLOB& from, LineBreak lb = LineBreak::eAuto_LB)
    {
        return Base64::Encode (from, Base64::Options{.fLineBreak = lb});
    }
 
}
 
/*
 ********************************************************************************
 ***************************** Implementation Details ***************************
 ********************************************************************************
 */
 
#endif /*_Stroika_Foundation_Cryptography_Base64_h_*/