1 /*==============================================================================
2  *
3  *                            PUBLIC DOMAIN NOTICE
4  *               National Center for Biotechnology Information
5  *
6  *  This software/database is a "United States Government Work" under the
7  *  terms of the United States Copyright Act.  It was written as part of
8  *  the author's official duties as a United States Government employee and
9  *  thus cannot be copyrighted.  This software/database is freely available
10  *  to the public for use. The National Library of Medicine and the U.S.
11  *  Government have not placed any restriction on its use or reproduction.
12  *
13  *  Although all reasonable efforts have been taken to ensure the accuracy
14  *  and reliability of the software and data, the NLM and the U.S.
15  *  Government do not and cannot warrant the performance or results that
16  *  may be obtained by using this software or data. The NLM and the U.S.
17  *  Government disclaim all warranties, express or implied, including
18  *  warranties of performance, merchantability or fitness for any particular
19  *  purpose.
20  *
21  *  Please cite the author in any work or product based on this material.
22  *
23  *  Author: Kurt Rodarmer
24  *
25  * ===========================================================================
26  *
27  */
28 
29 #pragma once
30 
31 #include <ncbi/secure/payload.hpp>
32 #include <ncbi/secure/string.hpp>
33 #include <ncbi/secure/except.hpp>
34 
35 
36 namespace ncbi
37 {
38 
39     /*=====================================================*
40      *                       Base64                        *
41      *=====================================================*/
42 
43     /**
44      * @class Base64
45      * @brief Base64 encoding management
46      */
47     class Base64
48     {
49     public:
50 
51         /**
52          * @var allow_whitespace
53          * @brief constant used to allow embedded whitespace in text
54          */
55         static const bool allow_whitespace = true;
56 
57         /**
58          * @var strict_charset
59          * @brief constant used to disallow any non-coding characters in text
60          */
61         static const bool strict_charset = false;
62 
63         /**
64          * encode
65          * @brief apply base64 encoding to binary payload
66          * @param payload pointer to start of binary payload to encode
67          * @param bytes size in bytes of binary payload to encode
68          * @return base64-encoded String
69          */
70         static const String encode ( const void * payload, size_t bytes );
71 
72         /**
73          * decode
74          * @brief remove base64 encoding from binary payload
75          * @param base64 the base64-encoded text
76          * @param allow_whitespace if true, allow whitespace in text
77          * @return Payload of extracted binary data
78          */
79         static const Payload decode ( const String & base64, bool allow_whitespace );
80 
81         /**
82          * decodeText
83          * @brief remove base64 encoding where content is expected to be UTF-8 text
84          * @param base64 the base64-encoded text
85          * @param allow_whitespace if true, allow whitespace in text
86          * @return String with extracted text
87          */
88         static const String decodeText ( const String & base64, bool allow_whitespace );
89 
90         /**
91          * urlEncode
92          * @brief apply base64-url encoding to binary payload
93          * @param payload pointer to start of binary payload to encode
94          * @param bytes size in bytes of binary payload to encode
95          * @return base64url-encoded String
96          */
97         static const String urlEncode ( const void * payload, size_t bytes );
98 
99         /**
100          * urlDecode
101          * @brief remove base64-url encoding from binary payload
102          * @param base64url the base64url-encoded text
103          * @param allow_whitespace if true, allow whitespace in text
104          * @return Payload of extracted binary data
105          */
106         static const Payload urlDecode ( const String & base64url, bool allow_whitespace );
107 
108         /**
109          * urlDecodeText
110          * @brief remove base64-url encoding where content is expected to be UTF-8 text
111          * @param base64url the base64url-encoded text
112          * @param allow_whitespace if true, allow whitespace in text
113          * @return String with extracted text
114          */
115         static const String urlDecodeText ( const String & base64url, bool allow_whitespace );
116 
117     private:
118 
119         Base64 ();
120     };
121 
122     /*=====================================================*
123      *                     EXCEPTIONS                      *
124      *=====================================================*/
125 
126 }
127