Commit c0a78a89 authored by JINMEI Tatuya's avatar JINMEI Tatuya
Browse files

[trac1104] overall documentation update

parent 6ba74546
......@@ -58,7 +58,9 @@ namespace dns {
/// The specialization of \c NameCheck for access control with
/// \c RequestContext.
///
/// TBD
/// It returns \c true if the request contains a TSIG record and its key
/// (owner) name is equal to the name stored in the check; otherwise
/// it returns \c false.
template<>
bool
NameCheck<RequestContext>::matches(const RequestContext& request) const {
......
......@@ -57,9 +57,9 @@ namespace dns {
* used only for a very short period as stated above.
*
* Based on the minimalist philosophy, the initial implementation only
* maintains the remote (source) IP address of the request. The plan is
* to add more parameters of the request. A scheduled next step is to
* support the TSIG key (if it's included in the request). Other possibilities
* maintains the remote (source) IP address of the request and (optionally)
* the TSIG record included in the request. We may add more parameters of
* the request as we see the need for them. Possible additional parameters
* are the local (destination) IP address, the remote and local port numbers,
* various fields of the DNS request (e.g. a particular header flag value).
*/
......@@ -72,8 +72,10 @@ struct RequestContext {
/// \exception None
///
/// \parameter remote_address_param The remote IP address
explicit RequestContext(const IPAddress& remote_address_param,
const isc::dns::TSIGRecord* tsig_param) :
/// \parameter tsig_param A valid pointer to the TSIG record included in
/// the request or NULL if the request doesn't contain a TSIG.
RequestContext(const IPAddress& remote_address_param,
const isc::dns::TSIGRecord* tsig_param) :
remote_address(remote_address_param),
tsig(tsig_param)
{}
......@@ -90,7 +92,9 @@ struct RequestContext {
/// \brief The remote IP address (eg. the client's IP address).
const IPAddress& remote_address;
/// TBD
/// \brief The TSIG record included in the request message, if any.
///
/// If the request doesn't include a TSIG, this member will be NULL.
const isc::dns::TSIGRecord* const tsig;
//@}
};
......
......@@ -23,24 +23,49 @@ namespace isc {
namespace acl {
namespace dns {
/// ACL check for DNS names
///
/// This class is intended to perform a match between a domain name
/// specified in an ACL and a given name. The primary usage of this class
/// is an ACL match for TSIG keys, where an ACL would contain a list of
/// acceptable key names and the \c match() method would compare the owner
/// name of a TSIG record against the specified names.
///
/// This class could be used for other kinds of names such as the query name
/// of normal DNS queries.
///
/// The class is templated on the type of a context structure passed to the
/// matches() method, and a template specialisation for that method must be
/// supplied for the class to be used.
template <typename Context>
class NameCheck : public Check<Context> {
public:
/// The constructor
///
/// \exception std::bad_alloc Resource allocation fails in copying the
/// name
///
/// \param name The domain name to be matched in \c matches().
NameCheck(const isc::dns::Name& name) : name_(name) {}
/// \brief Destructor
/// Destructor
virtual ~NameCheck() {}
/// \brief The check itself
/// The check method
///
/// Matches the passed argument to the condition stored here. Different
/// specialisations must be provided for different argument types, and the
/// specializations must be provided for different argument types, and the
/// program will fail to compile if a required specialisation is not
/// provided.
///
/// \param context Information to be matched
virtual bool matches(const Context& context) const;
/// Returns the name specified on construction.
///
/// This is mainly for testing purposes.
///
/// \exception None
const isc::dns::Name& getName() const { return (name_); }
private:
......
......@@ -5,18 +5,18 @@ DNS request to be checked.\n\
This plays the role of ACL context for the RequestACL object.\n\
\n\
Based on the minimalist philosophy, the initial implementation only\n\
maintains the remote (source) IP address of the request. The plan is\n\
to add more parameters of the request. A scheduled next step is to\n\
support the TSIG key (if it's included in the request). Other\n\
possibilities are the local (destination) IP address, the remote and\n\
local port numbers, various fields of the DNS request (e.g. a\n\
particular header flag value).\n\
maintains the remote (source) IP address of the request and\n\
(optionally) the TSIG record included in the request. We may add more\n\
parameters of the request as we see the need for them. Possible\n\
additional parameters are the local (destination) IP address, the\n\
remote and local port numbers, various fields of the DNS request (e.g.\n\
a particular header flag value).\n\
\n\
RequestContext(remote_address)\n\
RequestContext(remote_address, tsig)\n\
\n\
In this initial implementation, the constructor only takes a\n\
remote IP address in the form of a socket address as used in the\n\
Python socket module.\n\
Python socket module, and optionally a pydnspp.TSIGRecord object.\n\
\n\
Exceptions:\n\
isc.acl.ACLError Normally shouldn't happen, but still possible\n\
......@@ -25,6 +25,9 @@ RequestContext(remote_address)\n\
\n\
Parameters:\n\
remote_address The remote IP address\n\
tsig The TSIG record included in the request message, if any.\n\
If the request doesn't include a TSIG, this will be None.\n\
If this parameter is omitted None will be assumed.\n\
\n\
";
} // unnamed namespace
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment