From: Francis Dupont Date: Wed, 2 Jun 2021 16:53:54 +0000 (+0200) Subject: [(no branch, rebasing 1880-implement-the-tkey-rr)] [#1880] Added comments X-Git-Tag: Kea-1.9.9~136 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3b310c02e5dece02240c4e5747efb5c6e6daf439;p=thirdparty%2Fkea.git [(no branch, rebasing 1880-implement-the-tkey-rr)] [#1880] Added comments --- diff --git a/src/lib/dns/rdata/generic/tkey_249.cc b/src/lib/dns/rdata/generic/tkey_249.cc index 550d02ace4..886eb40375 100644 --- a/src/lib/dns/rdata/generic/tkey_249.cc +++ b/src/lib/dns/rdata/generic/tkey_249.cc @@ -37,6 +37,15 @@ const uint16_t TKEY::GSS_API_MODE = 3; // straightforward representation of TKEY RDATA fields struct TKEYImpl { + /// \brief Constructor from RDATA field parameters. + /// + /// \param algorithm The DNS name of the algorithm e.g. gss-tsig. + /// \param inception The inception time (in seconds since 1970). + /// \param expire The expire time (in seconds since 1970). + /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3). + /// \param error The error code (extended error space shared with TSIG). + /// \param key The key (can be empty). + /// \param other_data The other data (can be and usually is empty). TKEYImpl(const Name& algorithm, uint32_t inception, uint32_t expire, uint16_t mode, uint16_t error, vector& key, vector& other_data) : @@ -44,6 +53,17 @@ struct TKEYImpl { mode_(mode), error_(error), key_(key), other_data_(other_data) {} + /// \brief Constructor from RDATA field parameters. + /// + /// \param algorithm The DNS name of the algorithm e.g. gss-tsig. + /// \param inception The inception time (in seconds since 1970). + /// \param expire The expire time (in seconds since 1970). + /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3). + /// \param error The error code (extended error space shared with TSIG). + /// \param key_len The key length (0 means no key). + /// \param key The key (can be 0). + /// \param other_len The other data length (0 means no other data). + /// \param other_data The other data (can be and usually is 0). TKEYImpl(const Name& algorithm, uint32_t inception, uint32_t expire, uint16_t mode, uint16_t error, size_t key_len, const void* key, size_t other_len, const void* other_data) : @@ -55,15 +75,30 @@ struct TKEYImpl { static_cast(other_data) + other_len) {} + /// \brief Common part of toWire methods. + /// \tparam Output \c OutputBuffer or \c AbstractMessageRenderer. template void toWireCommon(Output& output) const; + /// \brief The DNS name of the algorithm e.g. gss-tsig. const Name algorithm_; + + /// \brief The inception time (in seconds since 1970). const uint32_t inception_; + + /// \brief The expire time (in seconds since 1970). const uint32_t expire_; + + /// \brief The mode e.g. Diffie-Hellman (2) or GSS-API (3). const uint16_t mode_; + + /// \brief The error code (extended error space shared with TSIG). const uint16_t error_; + + /// \brief The key (can be empty). const vector key_; + + /// \brief The other data (can be and usually is empty). const vector other_data_; }; @@ -183,10 +218,10 @@ TKEY::constructFromLexer(MasterLexer& lexer, const Name* origin) { /// syntax", but it is not actually a domain name, it does not have to be /// fully qualified. /// -/// The Mode field is an unsigned 16-bit decimal integer or a valid mnemonic -/// as specified in RFC2930. Currently only "GSS-API" (case sensitive) is -/// supported ("Diffie-Hellman" is not). - +/// The Mode field is an unsigned 16-bit decimal integer as specified +/// in RFC2930 or a common mnemonic. Currently only "GSS-API" (case sensitive) +/// is supported ("Diffie-Hellman" is not). +/// /// The Error field is an unsigned 16-bit decimal integer or a valid mnemonic /// as specified in RFC2845. Currently, "NOERROR", "BADSIG", "BADKEY", /// "BADTIME", "BADMODE", "BADNAME", and "BADALG" are supported diff --git a/src/lib/dns/rdata/generic/tkey_249.h b/src/lib/dns/rdata/generic/tkey_249.h index 687c2bfa72..d63012132d 100644 --- a/src/lib/dns/rdata/generic/tkey_249.h +++ b/src/lib/dns/rdata/generic/tkey_249.h @@ -43,6 +43,16 @@ public: /// /// This constructor internally involves resource allocation, and if /// it fails, a corresponding standard exception will be thrown. + /// + /// \param algorithm The DNS name of the algorithm e.g. gss-tsig. + /// \param inception The inception time (in seconds since 1970). + /// \param expire The expire time (in seconds since 1970). + /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3). + /// \param error The error code (extended error space shared with TSIG). + /// \param key_len The key length (0 means no key). + /// \param key The key (can be 0). + /// \param other_len The other data length (0 means no other data). + /// \param other_data The other data (can be and usually is 0). TKEY(const Name& algorithm, uint32_t inception, uint32_t expire, uint16_t mode, uint16_t error, uint16_t key_len, const void* key, uint16_t other_len, const void* other_data); diff --git a/src/lib/dns/rdataclass.cc b/src/lib/dns/rdataclass.cc index 4441884a3a..3a3de4aa33 100644 --- a/src/lib/dns/rdataclass.cc +++ b/src/lib/dns/rdataclass.cc @@ -5185,12 +5185,33 @@ const uint16_t TKEY::GSS_API_MODE = 3; // straightforward representation of TKEY RDATA fields struct TKEYImpl { + /// \brief Constructor from RDATA field parameters. + /// + /// \param algorithm The DNS name of the algorithm e.g. gss-tsig. + /// \param inception The inception time (in seconds since 1970). + /// \param expire The expire time (in seconds since 1970). + /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3). + /// \param error The error code (extended error space shared with TSIG). + /// \param key The key (can be empty). + /// \param other_data The other data (can be and usually is empty). TKEYImpl(const Name& algorithm, uint32_t inception, uint32_t expire, uint16_t mode, uint16_t error, vector& key, vector& other_data) : algorithm_(algorithm), inception_(inception), expire_(expire), mode_(mode), error_(error), key_(key), other_data_(other_data) {} + + /// \brief Constructor from RDATA field parameters. + /// + /// \param algorithm The DNS name of the algorithm e.g. gss-tsig. + /// \param inception The inception time (in seconds since 1970). + /// \param expire The expire time (in seconds since 1970). + /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3). + /// \param error The error code (extended error space shared with TSIG). + /// \param key_len The key length (0 means no key). + /// \param key The key (can be 0). + /// \param other_len The other data length (0 means no other data). + /// \param other_data The other data (can be and usually is 0). TKEYImpl(const Name& algorithm, uint32_t inception, uint32_t expire, uint16_t mode, uint16_t error, size_t key_len, const void* key, size_t other_len, const void* other_data) : @@ -5201,15 +5222,31 @@ struct TKEYImpl { other_data_(static_cast(other_data), static_cast(other_data) + other_len) {} + + /// \brief Common part of toWire methods. + /// \tparam Output \c OutputBuffer or \c AbstractMessageRenderer. template void toWireCommon(Output& output) const; + /// \brief The DNS name of the algorithm e.g. gss-tsig. const Name algorithm_; + + /// \brief The inception time (in seconds since 1970). const uint32_t inception_; + + /// \brief The expire time (in seconds since 1970). const uint32_t expire_; + + /// \brief The mode e.g. Diffie-Hellman (2) or GSS-API (3). const uint16_t mode_; + + /// \brief The error code (extended error space shared with TSIG). const uint16_t error_; + + /// \brief The key (can be empty). const vector key_; + + /// \brief The other data (can be and usually is empty). const vector other_data_; }; @@ -5225,6 +5262,8 @@ TKEY::constructFromLexer(MasterLexer& lexer, const Name* origin) { const uint32_t expire = timeFromText32(lexer.getNextToken(MasterToken::STRING).getString()); + /// The mode is either a mnemonic (only one is defined: GSS-API) or + /// a number. const string& mode_txt = lexer.getNextToken(MasterToken::STRING).getString(); uint32_t mode = 0; @@ -5237,7 +5276,7 @@ TKEY::constructFromLexer(MasterLexer& lexer, const Name* origin) { mode = boost::lexical_cast(mode_txt); } catch (const boost::bad_lexical_cast&) { isc_throw(InvalidRdataText, "Invalid TKEY Mode"); - } + } if (mode > 0xffff) { isc_throw(InvalidRdataText, "TKEY Mode out of range"); } @@ -5327,10 +5366,10 @@ TKEY::constructFromLexer(MasterLexer& lexer, const Name* origin) { /// syntax", but it is not actually a domain name, it does not have to be /// fully qualified. /// -/// The Mode field is an unsigned 16-bit decimal integer or a valid mnemonic -/// as specified in RFC2920. Currently only "GSS-API" (case sensitive) is -/// supported ("Diffie-Hellman" is not). - +/// The Mode field is an unsigned 16-bit decimal integer as specified +/// in RFC2930 or a common mnemonic. Currently only "GSS-API" (case sensitive) +/// is supported ("Diffie-Hellman" is not). +/// /// The Error field is an unsigned 16-bit decimal integer or a valid mnemonic /// as specified in RFC2845. Currently, "NOERROR", "BADSIG", "BADKEY", /// "BADTIME", "BADMODE", "BADNAME", and "BADALG" are supported @@ -5374,7 +5413,7 @@ TKEY::TKEY(const std::string& tkey_str) : impl_(0) { MasterLexer lexer; lexer.pushSource(ss); - impl_ptr.reset(constructFromLexer(lexer, NULL)); + impl_ptr.reset(constructFromLexer(lexer, 0)); if (lexer.getNextToken().getType() != MasterToken::END_OF_FILE) { isc_throw(InvalidRdataText, @@ -5431,7 +5470,7 @@ TKEY::TKEY(MasterLexer& lexer, const Name* origin, /// must check consistency between the length parameter and the actual /// RDATA length. TKEY::TKEY(InputBuffer& buffer, size_t) : - impl_(NULL) + impl_(0) { Name algorithm(buffer); @@ -5709,7 +5748,7 @@ TKEY::getOtherData() const { if (!impl_->other_data_.empty()) { return (&impl_->other_data_[0]); } else { - return (NULL); + return (0); } } diff --git a/src/lib/dns/rdataclass.h b/src/lib/dns/rdataclass.h index f42a867d63..aa7138ce09 100644 --- a/src/lib/dns/rdataclass.h +++ b/src/lib/dns/rdataclass.h @@ -2127,10 +2127,21 @@ public: /// The parameters are a straightforward mapping of %TKEY RDATA /// fields as defined %in RFC2930. /// - /// This RR is pretty close to the TSIG one with 32 bit timestamps. + /// This RR is pretty close to the TSIG RR with 32 bit timestamps, + /// or the RRSIG RR with a second "other" data field. /// /// This constructor internally involves resource allocation, and if /// it fails, a corresponding standard exception will be thrown. + /// + /// \param algorithm The DNS name of the algorithm e.g. gss-tsig. + /// \param inception The inception time (in seconds since 1970). + /// \param expire The expire time (in seconds since 1970). + /// \param mode The mode e.g. Diffie-Hellman (2) or GSS-API (3). + /// \param error The error code (extended error space shared with TSIG). + /// \param key_len The key length (0 means no key). + /// \param key The key (can be 0). + /// \param other_len The other data length (0 means no other data). + /// \param other_data The other data (can be and usually is 0). TKEY(const Name& algorithm, uint32_t inception, uint32_t expire, uint16_t mode, uint16_t error, uint16_t key_len, const void* key, uint16_t other_len, const void* other_data);