E-MailRelay

gsecret.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gsecret.h
19///
20
21#ifndef G_AUTH_SECRET_H
22#define G_AUTH_SECRET_H
23
24#include "gdef.h"
25#include "gstringview.h"
26#include "gexception.h"
27#include <utility>
28#include <string>
29
30 namespace GAuth
31{
32 class Secret ;
33}
34
35//| \class GAuth::Secret
36/// Encapsulates a userid/shared-secret/hash-function tuple from the secrets file.
37/// The shared secret can be a plaintext password or it can be a masked password
38/// using the given hash function. A masked secret can only be verified by an hmac
39/// operation using that hash function. However, the implementation of the hash
40/// function must be capable of accepting an intermediate hash state, and this
41/// might only be the case for md5.
42///
43 class GAuth::Secret
44{
45 public:
46 G_EXCEPTION( Error , tx("invalid authorisation secret") )
47 G_EXCEPTION( BadId , tx("invalid authorisation id") )
48 using Value = std::pair<std::string_view,std::string_view> ; // encoded value and encoding
49
50 Secret( Value id , Value secret , std::string_view masking_hash_function = {} ,
51 std::string_view context = {} ) ;
52 ///< Constructor used by the SecretsFile class. Throws on error,
53 ///< including if the encodings are invalid. Encodings should be
54 ///< empty (raw) or "xtext" or "base64" or "dotted".
55
56 static std::string check( Value id , Value secret ,
57 std::string_view masking_hash_function ) ;
58 ///< Does a non-throwing check of the constructor parameters,
59 ///< returning an error message or the empty string.
60
61 bool valid() const ;
62 ///< Returns true if the secret is valid.
63
64 std::string id() const ;
65 ///< Returns the associated identity. Throws if not valid().
66
67 std::string secret() const ;
68 ///< Returns the secret shared key. Throws if not valid().
69
70 bool masked() const ;
71 ///< Returns true if a non-empty hash function was passed
72 ///< to the ctor.
73
74 std::string maskHashFunction() const ;
75 ///< Returns the masking function name as passed to the ctor,
76 ///< such as "md5", or the empty string if not masked().
77 ///< Throws if not valid().
78
79 static Secret none() ;
80 ///< Factory function that returns a secret that is not valid().
81
82 std::string info( const std::string & id = {} ) const ;
83 ///< Returns information for logging, excluding anything
84 ///< sensitive. The secret may be in-valid().
85
86 static bool isDotted( std::string_view ) ;
87 ///< Returns true if the given secret string looks like it is in
88 ///< the old dotted format rather than base64.
89
90 static std::string decode( Value ) ;
91 ///< Decodes a value.
92
93 private:
94 enum class Encoding { xtext , base64 , raw , dotted } ;
95 Secret() ; // Secret::none()
96 static std::string undotted( std::string_view ) ;
97 static bool validEncodingType( Value ) ;
98 static bool validEncoding( Value ) ;
99 static Encoding encoding( Value ) ;
100
101 private:
102 std::string m_id ;
103 std::string m_secret ;
104 std::string m_hash_function ;
105 std::string m_context ;
106} ;
107
108#endif
GAuth::Secret
Encapsulates a userid/shared-secret/hash-function tuple from the secrets file.
Definition: gsecret.h:44
GAuth::Secret::secret
std::string secret() const
Returns the secret shared key. Throws if not valid().
Definition: gsecret.cpp:85
GAuth::Secret::masked
bool masked() const
Returns true if a non-empty hash function was passed to the ctor.
Definition: gsecret.cpp:91
GAuth::Secret::none
static Secret none()
Factory function that returns a secret that is not valid().
Definition: gsecret.cpp:75
GAuth::Secret::maskHashFunction
std::string maskHashFunction() const
Returns the masking function name as passed to the ctor, such as "md5", or the empty string if not ma...
Definition: gsecret.cpp:102
GAuth::Secret::valid
bool valid() const
Returns true if the secret is valid.
Definition: gsecret.cpp:80
GAuth::Secret::isDotted
static bool isDotted(std::string_view)
Returns true if the given secret string looks like it is in the old dotted format rather than base64.
Definition: gsecret.cpp:124
GAuth::Secret::info
std::string info(const std::string &id={}) const
Returns information for logging, excluding anything sensitive.
Definition: gsecret.cpp:108
GAuth::Secret::decode
static std::string decode(Value)
Decodes a value.
Definition: gsecret.cpp:187
GAuth::Secret::id
std::string id() const
Returns the associated identity. Throws if not valid().
Definition: gsecret.cpp:96
GAuth::Secret::check
static std::string check(Value id, Value secret, std::string_view masking_hash_function)
Does a non-throwing check of the constructor parameters, returning an error message or the empty stri...
Definition: gsecret.cpp:49
gexception.h
gstringview.h
GAuth
SASL authentication classes.
Definition: gcram.cpp:38
G::tx
constexpr const char * tx(const char *p) noexcept
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84