include/cryptopp/base64.h

0001 // base64.h - originally written and placed in the public domain by Wei Dai

0002
0003 /// \file base64.h

0004 /// \brief Classes for the Base64Encoder, Base64Decoder, Base64URLEncoder and Base64URLDecoder

0005
0006 #ifndef CRYPTOPP_BASE64_H
0007 #define CRYPTOPP_BASE64_H
0008
0009 #include "cryptlib.h"
0010 #include "basecode.h"
0011
0012 NAMESPACE_BEGIN(CryptoPP)
0013
0014 /// \brief Base64 encodes data using DUDE

0015 /// \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-4">RFC 4648, Base 64 Encoding</A>.

0016 class Base64Encoder : public SimpleProxyFilter
0017 {
0018 public:
0019     /// \brief Construct a Base64Encoder

0020     /// \param attachment a BufferedTrasformation to attach to this object

0021     /// \param insertLineBreaks a BufferedTrasformation to attach to this object

0022     /// \param maxLineLength the length of a line if line breaks are used

0023     /// \details Base64Encoder constructs a default encoder. The constructor lacks a parameter for padding, and you must

0024     ///   use IsolatedInitialize() to modify the Base64Encoder after construction.

0025     /// \sa IsolatedInitialize() for an example of modifying an encoder after construction.

0026     Base64Encoder(BufferedTransformation *attachment = NULLPTR, bool insertLineBreaks = true, int maxLineLength = 72)
0027         : SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment)
0028     {
0029         IsolatedInitialize(MakeParameters(Name::InsertLineBreaks(), insertLineBreaks)(Name::MaxLineLength(), maxLineLength));
0030     }
0031
0032     /// \brief Initialize or reinitialize this object, without signal propagation

0033     /// \param parameters a set of NameValuePairs used to initialize this object

0034     /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable

0035     ///   number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached

0036     ///   transformations. If initialization should be propagated, then use the Initialize() function.

0037     /// \details The following code modifies the padding and line break parameters for an encoder:

0038     ///   <pre>

0039     ///     Base64Encoder encoder;

0040     ///     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);

0041     ///     encoder.IsolatedInitialize(params);</pre>

0042     /// \details You can change the encoding to RFC 4648 web safe alphabet by performing the following:

0043     ///   <pre>

0044     ///     Base64Encoder encoder;

0045     ///     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";

0046     ///     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);

0047     ///     encoder.IsolatedInitialize(params);</pre>

0048     /// \details If you change the encoding alphabet, then you will need to change the decoding alphabet \a and

0049     ///   the decoder's lookup table.

0050     /// \sa Base64URLEncoder for an encoder that provides the web safe alphabet, and Base64Decoder::IsolatedInitialize()

0051     ///   for an example of modifying a decoder's lookup table after construction.

0052     void IsolatedInitialize(const NameValuePairs &parameters);
0053 };
0054
0055 /// \brief Base64 decodes data using DUDE

0056 /// \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-4">RFC 4648, Base 64 Encoding</A>.

0057 class Base64Decoder : public BaseN_Decoder
0058 {
0059 public:
0060     /// \brief Construct a Base64Decoder

0061     /// \param attachment a BufferedTrasformation to attach to this object

0062     /// \sa IsolatedInitialize() for an example of modifying an encoder after construction.

0063     Base64Decoder(BufferedTransformation *attachment = NULLPTR)
0064         : BaseN_Decoder(GetDecodingLookupArray(), 6, attachment) {}
0065
0066     /// \brief Initialize or reinitialize this object, without signal propagation

0067     /// \param parameters a set of NameValuePairs used to initialize this object

0068     /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable

0069     ///   number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached

0070     ///   transformations. If initialization should be propagated, then use the Initialize() function.

0071     /// \details The default decoding alpahbet is RFC 4868. You can change the to RFC 4868 web safe alphabet

0072     ///   by performing the following:

0073     ///   <pre>

0074     ///     int lookup[256];

0075     ///     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";

0076     ///     Base64Decoder::InitializeDecodingLookupArray(lookup, ALPHABET, 64, false);

0077     ///

0078     ///     Base64Decoder decoder;

0079     ///     AlgorithmParameters params = MakeParameters(Name::DecodingLookupArray(),(const int *)lookup);

0080     ///     decoder.IsolatedInitialize(params);</pre>

0081     /// \sa Base64URLDecoder for a decoder that provides the web safe alphabet, and Base64Encoder::IsolatedInitialize()

0082     ///   for an example of modifying an encoder's alphabet after construction.

0083     void IsolatedInitialize(const NameValuePairs &parameters);
0084
0085 private:
0086     /// \brief Provides the default decoding lookup table

0087     /// \return default decoding lookup table

0088     static const int * CRYPTOPP_API GetDecodingLookupArray();
0089 };
0090
0091 /// \brief Base64 encodes data using a web safe alphabet

0092 /// \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-5">RFC 4648, Base 64 Encoding

0093 ///   with URL and Filename Safe Alphabet</A>.

0094 class Base64URLEncoder : public SimpleProxyFilter
0095 {
0096 public:
0097     /// \brief Construct a Base64URLEncoder

0098     /// \param attachment a BufferedTrasformation to attach to this object

0099     /// \param insertLineBreaks a BufferedTrasformation to attach to this object

0100     /// \param maxLineLength the length of a line if line breaks are used

0101     /// \details Base64URLEncoder() constructs a default encoder using a web safe alphabet. The constructor ignores

0102     ///   insertLineBreaks and maxLineLength because the web and URL safe specifications don't use them. They are

0103     ///   present in the constructor for API compatibility with Base64Encoder so it is a drop-in replacement. The

0104     ///   constructor also disables padding on the encoder for the same reason.

0105     /// \details If you need line breaks or padding, then you must use IsolatedInitialize() to set them

0106     ///   after constructing a Base64URLEncoder.

0107     /// \sa Base64Encoder for an encoder that provides a classic alphabet, and Base64URLEncoder::IsolatedInitialize

0108     ///   for an example of modifying an encoder after construction.

0109     Base64URLEncoder(BufferedTransformation *attachment = NULLPTR, bool insertLineBreaks = false, int maxLineLength = -1)
0110         : SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment)
0111     {
0112         CRYPTOPP_UNUSED(insertLineBreaks), CRYPTOPP_UNUSED(maxLineLength);
0113         IsolatedInitialize(MakeParameters(Name::InsertLineBreaks(), false)(Name::MaxLineLength(), -1)(Name::Pad(),false));
0114     }
0115
0116     /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable

0117     ///   number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached

0118     ///   transformations. If initialization should be propagated, then use the Initialize() function.

0119     /// \details The following code modifies the padding and line break parameters for an encoder:

0120     ///   <pre>

0121     ///     Base64URLEncoder encoder;

0122     ///     AlgorithmParameters params = MakeParameters(Name::Pad(), true)(Name::InsertLineBreaks(), true);

0123     ///     encoder.IsolatedInitialize(params);</pre>

0124     /// \sa Base64Encoder for an encoder that provides a classic alphabet.

0125     void IsolatedInitialize(const NameValuePairs &parameters);
0126 };
0127
0128 /// \brief Base64 decodes data using a web safe alphabet

0129 /// \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-5">RFC 4648, Base 64 Encoding

0130 ///   with URL and Filename Safe Alphabet</A>.

0131 class Base64URLDecoder : public BaseN_Decoder
0132 {
0133 public:
0134     /// \brief Construct a Base64URLDecoder

0135     /// \param attachment a BufferedTrasformation to attach to this object

0136     /// \details Base64URLDecoder() constructs a default decoder using a web safe alphabet.

0137     /// \sa Base64Decoder for a decoder that provides a classic alphabet.

0138     Base64URLDecoder(BufferedTransformation *attachment = NULLPTR)
0139         : BaseN_Decoder(GetDecodingLookupArray(), 6, attachment) {}
0140
0141     /// \brief Initialize or reinitialize this object, without signal propagation

0142     /// \param parameters a set of NameValuePairs used to initialize this object

0143     /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable

0144     ///   number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on

0145     ///  attached transformations. If initialization should be propagated, then use the Initialize() function.

0146     /// \sa Base64Decoder for a decoder that provides a classic alphabet, and Base64URLEncoder::IsolatedInitialize

0147     ///   for an example of modifying an encoder after construction.

0148     void IsolatedInitialize(const NameValuePairs &parameters);
0149
0150 private:
0151     /// \brief Provides the default decoding lookup table

0152     /// \return default decoding lookup table

0153     static const int * CRYPTOPP_API GetDecodingLookupArray();
0154 };
0155
0156 NAMESPACE_END
0157
0158 #endif