/src/kea/src/bin/agent/ca_cfg_mgr.h

Source
// Copyright (C) 2016-2024 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.

#ifndef CTRL_AGENT_CFG_MGR_H
#define CTRL_AGENT_CFG_MGR_H

#include <cc/data.h>
#include <hooks/hooks_config.h>
#include <http/auth_config.h>
#include <http/cfg_http_header.h>
#include <process/d_cfg_mgr.h>
#include <boost/pointer_cast.hpp>
#include <map>
#include <string>

namespace isc {
namespace agent {

class CtrlAgentCfgContext;
/// @brief Pointer to a configuration context.
typedef boost::shared_ptr<CtrlAgentCfgContext> CtrlAgentCfgContextPtr;

/// @brief Control Agent Configuration Context.
///
/// Implement the storage container for configuration context.
/// It provides a single enclosure for the storage of configuration parameters
/// and any other Control Agent specific information that needs to be accessible
/// during configuration parsing as well as to the application as a whole.
/// It is derived from the context base class, ConfigBase.
class CtrlAgentCfgContext : public process::ConfigBase {
public:

    /// @brief Default constructor
    CtrlAgentCfgContext();

    /// @brief Creates a clone of this context object.
    ///
    /// Note this method does not do deep copy the information about control sockets.
    /// That data is stored as ConstElementPtr (a shared pointer) to the actual data.
    ///
    /// @return A pointer to the new clone.
    virtual process::ConfigPtr clone() {
        return (process::ConfigPtr(new CtrlAgentCfgContext(*this)));
    }

    /// @brief Returns information about control socket
    ///
    /// This method returns Element tree structure that describes the control
    /// socket (or null pointer if the socket is not defined for a particular
    /// server type). This information is expected to be compatible with
    /// data passed to @ref isc::config::UnixCommandMgr::openCommandSocket.
    ///
    /// @param service server being controlled
    /// @return pointer to the Element that holds control-socket map (or NULL)
    isc::data::ConstElementPtr
    getControlSocketInfo(const std::string& service) const;

    /// @brief Sets information about the control socket
    ///
    /// This method stores Element tree structure that describes the control
    /// socket. This information is expected to be compatible with
    /// data passed to @ref isc::config::UnixCommandMgr::openCommandSocket.
    ///
    /// @param control_socket Element that holds control-socket map
    /// @param service server being controlled
    void setControlSocketInfo(const isc::data::ConstElementPtr& control_socket,
                              const std::string& service);

    /// @brief Returns socket configuration summary in a textual format.
    std::string getControlSocketInfoSummary() const;

    /// @brief Sets http-host parameter
    ///
    /// @param host Hostname or IP address where the agent's HTTP service
    /// will be available.
    void setHttpHost(const std::string& host) {
        http_host_ = host;
    }

    /// @brief Returns http-host parameter
    ///
    /// @return Hostname or IP address where the agent's HTTP service is
    /// available.
    std::string getHttpHost() const {
        return (http_host_);
    }

    /// @brief Sets http port
    ///
    /// @param port sets the TCP port the HTTP server will listen on
    void setHttpPort(const uint16_t port) {
        http_port_ = port;
    }

    /// @brief Returns the TCP post the HTTP server will listen on
    uint16_t getHttpPort() const {
        return (http_port_);
    }

    /// @brief Sets http-headers parameter
    ///
    /// @param headers Collection of config HTTP headers.
    void setHttpHeaders(const isc::http::CfgHttpHeaders& headers) {
        http_headers_ = headers;
    }

    /// @brief Returns http-headers parameter
    ///
    /// @return Collection of config HTTP headers.
    const isc::http::CfgHttpHeaders& getHttpHeaders() const {
        return (http_headers_);
    }

    /// @brief Sets HTTP authentication configuration.
    ///
    /// @note Only the basic HTTP authentication is supported.
    ///
    /// @param auth_config HTTP authentication configuration.
    void setAuthConfig(const isc::http::HttpAuthConfigPtr& auth_config) {
        auth_config_ = auth_config;
    }

    /// @brief Returns HTTP authentication configuration
    ///
    /// @note Only the basic HTTP authentication is supported.
    ///
    /// @return HTTP authentication configuration.
    const isc::http::HttpAuthConfigPtr& getAuthConfig() const {
        return (auth_config_);
    }

    /// @brief Sets trust-anchor parameter
    ///
    /// @param ca Trust anchor aka Certificate Authority (can be a file name
    /// or a directory path).
    void setTrustAnchor(const std::string& ca) {
        trust_anchor_ = ca;
    }

    /// @brief Returns trust-anchor parameter
    ///
    /// @return Trust anchor aka Certificate Authority
    std::string getTrustAnchor() const {
        return (trust_anchor_);
    }

    /// @brief Sets cert-file parameter
    ///
    /// @param cert Server certificate file name
    void setCertFile(const std::string& cert) {
        cert_file_ = cert;
    }

    /// @brief Returns cert-file parameter
    ///
    /// @return Server certificate file name
    std::string getCertFile() const {
        return (cert_file_);
    }

    /// @brief Sets key-file parameter
    ///
    /// @param key Server private key file name
    void setKeyFile(const std::string& key) {
        key_file_ = key;
    }

    /// @brief Returns key-file parameter
    ///
    /// @return Server private key file name
    std::string getKeyFile() const {
        return (key_file_);
    }

    /// @brief Sets cert-required parameter
    ///
    /// @param required Client certificates are required when true
    /// (the default) or optional when false
    void setCertRequired(bool required) {
        cert_required_ = required;
    }

    /// @brief Returns cert-required parameter
    ///
    /// @return True when client certificates are required, false when they
    /// are optional, the default is to require them (true).
    bool getCertRequired() const {
        return (cert_required_);
    }

    /// @brief Returns non-const reference to configured hooks libraries.
    ///
    /// @return non-const reference to configured hooks libraries.
    isc::hooks::HooksConfig& getHooksConfig() {
        return (hooks_config_);
    }

    /// @brief Returns const reference to configured hooks libraries.
    ///
    /// @return const reference to configured hooks libraries.
    const isc::hooks::HooksConfig& getHooksConfig() const {
        return (hooks_config_);
    }

    /// @brief Unparse a configuration object
    ///
    /// Returns an element which must parse into the same object, i.e.
    /// @code
    /// for all valid config C parse(parse(C)->toElement()) == parse(C)
    /// @endcode
    ///
    /// @return a pointer to a configuration which can be parsed into
    /// the initial configuration object
    virtual isc::data::ElementPtr toElement() const;

private:

    /// @brief Private copy constructor
    ///
    /// It is private to forbid anyone outside of this class to make copies.
    /// The only legal way to copy a context is to call @ref clone().
    ///
    /// @param orig the original context to copy from
    CtrlAgentCfgContext(const CtrlAgentCfgContext& orig);

    /// @brief Private assignment operator to avoid potential for slicing.
    ///
    /// @param rhs Context to be assigned.
    CtrlAgentCfgContext& operator=(const CtrlAgentCfgContext& rhs);

    /// Socket information will be stored here (for all supported servers)
    std::map<std::string, isc::data::ConstElementPtr> ctrl_sockets_;

    /// Hostname the CA should listen on.
    std::string http_host_;

    /// TCP port the CA should listen on.
    uint16_t http_port_;

    /// Config HTTP headers.
    isc::http::CfgHttpHeaders http_headers_;

    /// Trust anchor aka Certificate Authority (can be a file name or
    /// a directory path).
    std::string trust_anchor_;

    /// Server certificate file name.
    std::string cert_file_;

    /// Server private key file name.
    std::string key_file_;

    /// Client certificates requirement flag (default is true i.e. to
    /// require them).
    bool cert_required_;

    /// @brief Configured hooks libraries.
    isc::hooks::HooksConfig hooks_config_;

    /// @brief Configured basic HTTP authentification clients.
    isc::http::HttpAuthConfigPtr auth_config_;
};

/// @brief Ctrl Agent Configuration Manager.
///
/// Provides the mechanisms for managing the Control Agent application's
/// configuration.
class CtrlAgentCfgMgr : public process::DCfgMgrBase {
public:

    /// @brief Constructor.
    CtrlAgentCfgMgr();

    /// @brief Destructor
    virtual ~CtrlAgentCfgMgr();

    /// @brief Convenience method that returns the Control Agent configuration
    /// context.
    ///
    /// @return returns a pointer to the configuration context.
    CtrlAgentCfgContextPtr getCtrlAgentCfgContext() {
        return (boost::dynamic_pointer_cast<CtrlAgentCfgContext>(getContext()));
    }

    /// @brief Returns configuration summary in the textual format.
    ///
    /// @param selection Bitfield which describes the parts of the configuration
    /// to be returned. This parameter is ignored for the Control Agent.
    ///
    /// @return Summary of the configuration in the textual format.
    virtual std::string getConfigSummary(const uint32_t selection) override;

protected:

    /// @brief Parses configuration of the Control Agent.
    ///
    /// @param config Pointer to a configuration specified for the agent.
    /// @param check_only Boolean flag indicating if this method should
    /// only verify correctness of the provided configuration.
    /// @return Pointer to a result of configuration parsing.
    virtual isc::data::ConstElementPtr
    parse(isc::data::ConstElementPtr config, bool check_only) override;

    /// @brief Creates a new, blank CtrlAgentCfgContext context.
    ///
    ///
    /// This method is used at the beginning of configuration process to
    /// create a fresh, empty copy of a CtrlAgentCfgContext. This new context
    /// will be populated during the configuration process and will replace the
    /// existing context provided the configuration process completes without
    /// error.
    ///
    /// @return Returns a ConfigPtr to the new context instance.
    virtual process::ConfigPtr createNewContext() override;

    /// @brief Return a list of all paths that contain passwords or secrets.
    ///
    /// Used in @ref isc::process::DCfgMgrBase::redactConfig.
    ///
    /// @return the list of lists of sequential JSON map keys needed to reach
    /// the passwords and secrets.
    std::list<std::list<std::string>> jsonPathsToRedact() const final override;
};

/// @brief Defines a shared pointer to CtrlAgentCfgMgr.
typedef boost::shared_ptr<CtrlAgentCfgMgr> CtrlAgentCfgMgrPtr;

} // namespace isc::agent
} // namespace isc

#endif // CTRL_AGENT_CFG_MGR_H

Coverage Report

Created: 2026-03-31 07:26

Line	Count	Source
1		// Copyright (C) 2016-2024 Internet Systems Consortium, Inc. ("ISC")
2		//
3		// This Source Code Form is subject to the terms of the Mozilla Public
4		// License, v. 2.0. If a copy of the MPL was not distributed with this
5		// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7		#ifndef CTRL_AGENT_CFG_MGR_H
8		#define CTRL_AGENT_CFG_MGR_H
9
10		#include <cc/data.h>
11		#include <hooks/hooks_config.h>
12		#include <http/auth_config.h>
13		#include <http/cfg_http_header.h>
14		#include <process/d_cfg_mgr.h>
15		#include <boost/pointer_cast.hpp>
16		#include <map>
17		#include <string>
18
19		namespace isc {
20		namespace agent {
21
22		class CtrlAgentCfgContext;
23		/// @brief Pointer to a configuration context.
24		typedef boost::shared_ptr<CtrlAgentCfgContext> CtrlAgentCfgContextPtr;
25
26		/// @brief Control Agent Configuration Context.
27		///
28		/// Implement the storage container for configuration context.
29		/// It provides a single enclosure for the storage of configuration parameters
30		/// and any other Control Agent specific information that needs to be accessible
31		/// during configuration parsing as well as to the application as a whole.
32		/// It is derived from the context base class, ConfigBase.
33		class CtrlAgentCfgContext : public process::ConfigBase {
34		public:
35
36		/// @brief Default constructor
37		CtrlAgentCfgContext();
38
39		/// @brief Creates a clone of this context object.
40		///
41		/// Note this method does not do deep copy the information about control sockets.
42		/// That data is stored as ConstElementPtr (a shared pointer) to the actual data.
43		///
44		/// @return A pointer to the new clone.
45	0	virtual process::ConfigPtr clone() {
46	0	return (process::ConfigPtr(new CtrlAgentCfgContext(*this)));
47	0	}
48
49		/// @brief Returns information about control socket
50		///
51		/// This method returns Element tree structure that describes the control
52		/// socket (or null pointer if the socket is not defined for a particular
53		/// server type). This information is expected to be compatible with
54		/// data passed to @ref isc::config::UnixCommandMgr::openCommandSocket.
55		///
56		/// @param service server being controlled
57		/// @return pointer to the Element that holds control-socket map (or NULL)
58		isc::data::ConstElementPtr
59		getControlSocketInfo(const std::string& service) const;
60
61		/// @brief Sets information about the control socket
62		///
63		/// This method stores Element tree structure that describes the control
64		/// socket. This information is expected to be compatible with
65		/// data passed to @ref isc::config::UnixCommandMgr::openCommandSocket.
66		///
67		/// @param control_socket Element that holds control-socket map
68		/// @param service server being controlled
69		void setControlSocketInfo(const isc::data::ConstElementPtr& control_socket,
70		const std::string& service);
71
72		/// @brief Returns socket configuration summary in a textual format.
73		std::string getControlSocketInfoSummary() const;
74
75		/// @brief Sets http-host parameter
76		///
77		/// @param host Hostname or IP address where the agent's HTTP service
78		/// will be available.
79	1.50k	void setHttpHost(const std::string& host) {
80	1.50k	http_host_ = host;
81	1.50k	}
82
83		/// @brief Returns http-host parameter
84		///
85		/// @return Hostname or IP address where the agent's HTTP service is
86		/// available.
87	0	std::string getHttpHost() const {
88	0	return (http_host_);
89	0	}
90
91		/// @brief Sets http port
92		///
93		/// @param port sets the TCP port the HTTP server will listen on
94	1.36k	void setHttpPort(const uint16_t port) {
95	1.36k	http_port_ = port;
96	1.36k	}
97
98		/// @brief Returns the TCP post the HTTP server will listen on
99	0	uint16_t getHttpPort() const {
100	0	return (http_port_);
101	0	}
102
103		/// @brief Sets http-headers parameter
104		///
105		/// @param headers Collection of config HTTP headers.
106	60	void setHttpHeaders(const isc::http::CfgHttpHeaders& headers) {
107	60	http_headers_ = headers;
108	60	}
109
110		/// @brief Returns http-headers parameter
111		///
112		/// @return Collection of config HTTP headers.
113	0	const isc::http::CfgHttpHeaders& getHttpHeaders() const {
114	0	return (http_headers_);
115	0	}
116
117		/// @brief Sets HTTP authentication configuration.
118		///
119		/// @note Only the basic HTTP authentication is supported.
120		///
121		/// @param auth_config HTTP authentication configuration.
122	5	void setAuthConfig(const isc::http::HttpAuthConfigPtr& auth_config) {
123	5	auth_config_ = auth_config;
124	5	}
125
126		/// @brief Returns HTTP authentication configuration
127		///
128		/// @note Only the basic HTTP authentication is supported.
129		///
130		/// @return HTTP authentication configuration.
131	0	const isc::http::HttpAuthConfigPtr& getAuthConfig() const {
132	0	return (auth_config_);
133	0	}
134
135		/// @brief Sets trust-anchor parameter
136		///
137		/// @param ca Trust anchor aka Certificate Authority (can be a file name
138		/// or a directory path).
139	1.36k	void setTrustAnchor(const std::string& ca) {
140	1.36k	trust_anchor_ = ca;
141	1.36k	}
142
143		/// @brief Returns trust-anchor parameter
144		///
145		/// @return Trust anchor aka Certificate Authority
146	0	std::string getTrustAnchor() const {
147	0	return (trust_anchor_);
148	0	}
149
150		/// @brief Sets cert-file parameter
151		///
152		/// @param cert Server certificate file name
153	1.36k	void setCertFile(const std::string& cert) {
154	1.36k	cert_file_ = cert;
155	1.36k	}
156
157		/// @brief Returns cert-file parameter
158		///
159		/// @return Server certificate file name
160	0	std::string getCertFile() const {
161	0	return (cert_file_);
162	0	}
163
164		/// @brief Sets key-file parameter
165		///
166		/// @param key Server private key file name
167	1.36k	void setKeyFile(const std::string& key) {
168	1.36k	key_file_ = key;
169	1.36k	}
170
171		/// @brief Returns key-file parameter
172		///
173		/// @return Server private key file name
174	0	std::string getKeyFile() const {
175	0	return (key_file_);
176	0	}
177
178		/// @brief Sets cert-required parameter
179		///
180		/// @param required Client certificates are required when true
181		/// (the default) or optional when false
182	1.36k	void setCertRequired(bool required) {
183	1.36k	cert_required_ = required;
184	1.36k	}
185
186		/// @brief Returns cert-required parameter
187		///
188		/// @return True when client certificates are required, false when they
189		/// are optional, the default is to require them (true).
190	0	bool getCertRequired() const {
191	0	return (cert_required_);
192	0	}
193
194		/// @brief Returns non-const reference to configured hooks libraries.
195		///
196		/// @return non-const reference to configured hooks libraries.
197	978	isc::hooks::HooksConfig& getHooksConfig() {
198	978	return (hooks_config_);
199	978	}
200
201		/// @brief Returns const reference to configured hooks libraries.
202		///
203		/// @return const reference to configured hooks libraries.
204	0	const isc::hooks::HooksConfig& getHooksConfig() const {
205	0	return (hooks_config_);
206	0	}
207
208		/// @brief Unparse a configuration object
209		///
210		/// Returns an element which must parse into the same object, i.e.
211		/// @code
212		/// for all valid config C parse(parse(C)->toElement()) == parse(C)
213		/// @endcode
214		///
215		/// @return a pointer to a configuration which can be parsed into
216		/// the initial configuration object
217		virtual isc::data::ElementPtr toElement() const;
218
219		private:
220
221		/// @brief Private copy constructor
222		///
223		/// It is private to forbid anyone outside of this class to make copies.
224		/// The only legal way to copy a context is to call @ref clone().
225		///
226		/// @param orig the original context to copy from
227		CtrlAgentCfgContext(const CtrlAgentCfgContext& orig);
228
229		/// @brief Private assignment operator to avoid potential for slicing.
230		///
231		/// @param rhs Context to be assigned.
232		CtrlAgentCfgContext& operator=(const CtrlAgentCfgContext& rhs);
233
234		/// Socket information will be stored here (for all supported servers)
235		std::map<std::string, isc::data::ConstElementPtr> ctrl_sockets_;
236
237		/// Hostname the CA should listen on.
238		std::string http_host_;
239
240		/// TCP port the CA should listen on.
241		uint16_t http_port_;
242
243		/// Config HTTP headers.
244		isc::http::CfgHttpHeaders http_headers_;
245
246		/// Trust anchor aka Certificate Authority (can be a file name or
247		/// a directory path).
248		std::string trust_anchor_;
249
250		/// Server certificate file name.
251		std::string cert_file_;
252
253		/// Server private key file name.
254		std::string key_file_;
255
256		/// Client certificates requirement flag (default is true i.e. to
257		/// require them).
258		bool cert_required_;
259
260		/// @brief Configured hooks libraries.
261		isc::hooks::HooksConfig hooks_config_;
262
263		/// @brief Configured basic HTTP authentification clients.
264		isc::http::HttpAuthConfigPtr auth_config_;
265		};
266
267		/// @brief Ctrl Agent Configuration Manager.
268		///
269		/// Provides the mechanisms for managing the Control Agent application's
270		/// configuration.
271		class CtrlAgentCfgMgr : public process::DCfgMgrBase {
272		public:
273
274		/// @brief Constructor.
275		CtrlAgentCfgMgr();
276
277		/// @brief Destructor
278		virtual ~CtrlAgentCfgMgr();
279
280		/// @brief Convenience method that returns the Control Agent configuration
281		/// context.
282		///
283		/// @return returns a pointer to the configuration context.
284	0	CtrlAgentCfgContextPtr getCtrlAgentCfgContext() {
285	0	return (boost::dynamic_pointer_cast<CtrlAgentCfgContext>(getContext()));
286	0	}
287
288		/// @brief Returns configuration summary in the textual format.
289		///
290		/// @param selection Bitfield which describes the parts of the configuration
291		/// to be returned. This parameter is ignored for the Control Agent.
292		///
293		/// @return Summary of the configuration in the textual format.
294		virtual std::string getConfigSummary(const uint32_t selection) override;
295
296		protected:
297
298		/// @brief Parses configuration of the Control Agent.
299		///
300		/// @param config Pointer to a configuration specified for the agent.
301		/// @param check_only Boolean flag indicating if this method should
302		/// only verify correctness of the provided configuration.
303		/// @return Pointer to a result of configuration parsing.
304		virtual isc::data::ConstElementPtr
305		parse(isc::data::ConstElementPtr config, bool check_only) override;
306
307		/// @brief Creates a new, blank CtrlAgentCfgContext context.
308		///
309		///
310		/// This method is used at the beginning of configuration process to
311		/// create a fresh, empty copy of a CtrlAgentCfgContext. This new context
312		/// will be populated during the configuration process and will replace the
313		/// existing context provided the configuration process completes without
314		/// error.
315		///
316		/// @return Returns a ConfigPtr to the new context instance.
317		virtual process::ConfigPtr createNewContext() override;
318
319		/// @brief Return a list of all paths that contain passwords or secrets.
320		///
321		/// Used in @ref isc::process::DCfgMgrBase::redactConfig.
322		///
323		/// @return the list of lists of sequential JSON map keys needed to reach
324		/// the passwords and secrets.
325		std::list<std::list<std::string>> jsonPathsToRedact() const final override;
326		};
327
328		/// @brief Defines a shared pointer to CtrlAgentCfgMgr.
329		typedef boost::shared_ptr<CtrlAgentCfgMgr> CtrlAgentCfgMgrPtr;
330
331		} // namespace isc::agent
332		} // namespace isc
333
334		#endif // CTRL_AGENT_CFG_MGR_H