correct the DbC assertions in message.c

the comments for some calls in the dns_message API specified
requirements which were not actually enforced in the functions.

in most cases, this has now been corrected by adding the missing
REQUIREs. in one case, the comment was incorrect and has been
revised.

(cherry picked from commit c437da59ee78df59ce8708fa87a489154745a383)

diff --git a/lib/dns/include/dns/message.h b/lib/dns/include/dns/message.h
index 6a70665ba7c2c5d562f9532b869bc2c8622950c2..3097612839ef250b6cb34c4c40ade218d4b1379e 100644 (file)
--- a/lib/dns/include/dns/message.h
+++ b/lib/dns/include/dns/message.h
@@ -474,7 +474,7 @@ dns_message_totext(dns_message_t *msg, const dns_master_style_t *style,
  *     ";;" will be emitted indicating section name.
  *\li  If #DNS_MESSAGETEXTFLAG_NOHEADERS is cleared, header lines will be
  *     emitted.
- *\li   If #DNS_MESSAGETEXTFLAG_ONESOA is set then only print the first
+ *\li  If #DNS_MESSAGETEXTFLAG_ONESOA is set then only print the first
  *     SOA record in the answer section.
  *\li  If *#DNS_MESSAGETEXTFLAG_OMITSOA is set don't print any SOA records
  *     in the answer section.
@@ -535,9 +535,9 @@ dns_message_parse(dns_message_t *msg, isc_buffer_t *source,
  * 'preserve_order' setting.
  *
  * Requires:
- *\li  "msg" be valid.
+ *\li  "msg" be a valid message with parsing intent.
  *
- *\li  "buffer" be a wire format buffer.
+ *\li  "source" be a wire format buffer.
  *
  * Ensures:
  *\li  The buffer's data format is correct.
@@ -568,7 +568,9 @@ dns_message_renderbegin(dns_message_t *msg, dns_compress_t *cctx,
  *
  * Requires:
  *
- *\li  'msg' be valid.
+ *\li  'msg' be a valid message with rendering intent.
+ *
+ *\li  dns_message_renderbegin() has not previously been called.
  *
  *\li  'cctx' be valid.
  *
@@ -618,8 +620,6 @@ dns_message_renderreserve(dns_message_t *msg, unsigned int space);
  *
  *\li  'msg' be valid.
  *
- *\li  dns_message_renderbegin() was called.
- *
  * Returns:
  *\li  #ISC_R_SUCCESS          -- all is well.
  *\li  #ISC_R_NOSPACE          -- not enough free space in the buffer.
@@ -639,8 +639,6 @@ dns_message_renderrelease(dns_message_t *msg, unsigned int space);
  *
  *\li  'space' is less than or equal to the total amount of space reserved
  *     via prior calls to dns_message_renderreserve().
- *
- *\li  dns_message_renderbegin() was called.
  */
 
 isc_result_t
@@ -723,7 +721,7 @@ dns_message_firstname(dns_message_t *msg, dns_section_t section);
  *
  * Requires:
  *
- *\li          'msg' be valid.
+ *\li  'msg' be valid.
  *
  *\li  'section' be a valid section.
  *
@@ -740,7 +738,7 @@ dns_message_nextname(dns_message_t *msg, dns_section_t section);
  *
  * Requires:
  *
- * \li         'msg' be valid.
+ *\li  'msg' be valid.
  *
  *\li  'section' be a valid section.
  *
@@ -860,7 +858,7 @@ dns_message_removename(dns_message_t *msg, dns_name_t *name,
  *
  * Requires:
  *
- *\li  'msg' be valid, and be a renderable message.
+ *\li  'msg' be a valid message with rendering intent.
  *
  *\li  'name' be a valid absolute name.
  *
@@ -1023,7 +1021,7 @@ dns_message_reply(dns_message_t *msg, bool want_question_section);
  *
  * Requires:
  *
- *\li  'msg' is a valid message with parsing intent, and contains a query.
+ *\li  'msg' is a valid message which contains a query.
  *
  * Ensures:
  *
@@ -1071,7 +1069,7 @@ dns_message_setopt(dns_message_t *msg, dns_rdataset_t *opt);
  *\li  'msg' is a valid message with rendering intent
  *     and no sections have been rendered.
  *
- *\li  'opt' is a valid OPT record or NULL.
+ *\li  'opt' is a valid OPT rdataset or NULL.
  *
  * Ensures:
  *
@@ -1104,21 +1102,20 @@ dns_message_gettsig(dns_message_t *msg, const dns_name_t **owner);
  *
  * Ensures:
  *
- * \li If 'owner' is not NULL, it will point to the owner name.
+ *\li  If 'owner' is not NULL, it will point to the owner name.
  */
 
 isc_result_t
 dns_message_settsigkey(dns_message_t *msg, dns_tsigkey_t *key);
 /*%<
  * Set the tsig key for 'msg'.  This is only necessary for when rendering a
- * query or parsing a response.  The key (if non-NULL) is attached to, and
- * will be detached when the message is destroyed.
+ * query or parsing a response.  The key (if non-NULL) is attached to
+ * to the message, and will be detached when the message is destroyed.
  *
  * Requires:
  *
- *\li  'msg' is a valid message with rendering intent,
- *     dns_message_renderbegin() has been called, and no sections have been
- *     rendered.
+ *\li  'msg' is a valid message.
+ *
  *\li  'key' is a valid tsig key or NULL.
  *
  * Returns:
@@ -1135,7 +1132,8 @@ dns_message_gettsigkey(dns_message_t *msg);
  *
  * Requires:
  *
- *\li  'msg' is a valid message
+ *\li  'msg' is a valid message, and dns_message_settsigkey() has been
+ *     run previously.
  */
 
 void
@@ -1147,10 +1145,11 @@ dns_message_setquerytsig(dns_message_t *msg, isc_buffer_t *querytsig);
  *
  * Requires:
  *
- *\li  'querytsig' is a valid buffer as returned by dns_message_getquerytsig()
+ *\li  'querytsig' is a valid buffer as returned by dns_message_getquerytsig(),
  *     or NULL
  *
- *\li  'msg' is a valid message
+ *\li  'msg' is a valid message on which dns_message_setquerytsig() has
+ *     not previously been run.
  */
 
 isc_result_t
@@ -1193,7 +1192,7 @@ dns_message_getsig0(dns_message_t *msg, const dns_name_t **owner);
  *
  * Ensures:
  *
- * \li If 'owner' is not NULL, it will point to the owner name.
+ *\li  If 'owner' is not NULL, it will point to the owner name.
  */
 
 isc_result_t
@@ -1249,7 +1248,7 @@ dns_message_signer(dns_message_t *msg, dns_name_t *signer);
  *
  * Requires:
  *
- *\li  msg is a valid parsed message.
+ *\li  msg is a valid message with parsing intent.
  *\li  signer is a valid name
  *
  * Returns:
@@ -1398,18 +1397,13 @@ dns_message_logfmtpacket(dns_message_t *message, const char *description,
  * For dns_message_logpacket and dns_message_logfmtpacket expect the
  * 'description' to end in a newline.
  *
- * For dns_message_logpacket2 and dns_message_logfmtpacket2
- * 'description' will be emitted at the start of the message followed
- * by the formatted address and a newline.
- *
  * Requires:
- * \li   message be a valid.
- * \li   description to be non NULL.
- * \li   address to be non NULL.
- * \li   category to be valid.
- * \li   module to be valid.
- * \li   style to be valid.
- * \li   mctx to be a valid.
+ *\li  'message' be a valid DNS message.
+ *\li  'description' to be non-NULL.
+ *\li  'address' to be non-NULL.
+ *\li  'category' to be a valid logging category.
+ *\li  'module' to be a valid logging module.
+ *\li  'mctx' to be a valid memory context.
  */
 
 isc_result_t
@@ -1420,14 +1414,12 @@ dns_message_buildopt(dns_message_t *msg, dns_rdataset_t **opt,
  * Built a opt record.
  *
  * Requires:
- * \li   msg be a valid message.
- * \li   opt to be a non NULL and *opt to be NULL.
+ *\li  msg be a valid message.
+ *\li  opt to be a non NULL and *opt to be NULL.
  *
  * Returns:
- * \li  ISC_R_SUCCESS on success.
- * \li  ISC_R_NOMEMORY
- * \li  ISC_R_NOSPACE
- * \li  other.
+ *\li   ISC_R_SUCCESS
+ *\li   ISC_R_NOSPACE
  */
 
 void
@@ -1436,7 +1428,7 @@ dns_message_setclass(dns_message_t *msg, dns_rdataclass_t rdclass);
  * Set the expected class of records in the response.
  *
  * Requires:
- * \li   msg be a valid message with parsing intent.
+ *\li  msg be a valid message with parsing intent.
  */
 
 void
@@ -1446,7 +1438,7 @@ dns_message_setpadding(dns_message_t *msg, uint16_t padding);
  * 0 means no padding (default).
  *
  * Requires:
- * \li msg be a valid message.
+ *\li  msg be a valid message.
  */
 
 void
@@ -1456,7 +1448,7 @@ dns_message_clonebuffer(dns_message_t *msg);
  * when parsing.
  *
  * Requires:
- * \li   msg be a valid message.
+ *\li  msg be a valid message.
  */
 
 isc_result_t
@@ -1467,8 +1459,8 @@ dns_message_minttl(dns_message_t *msg, const dns_section_t sectionid,
  * message.
  *
  * Requires:
- * \li   msg be a valid rendered message;
- * \li   'pttl != NULL'.
+ *\li  msg be a valid rendered message;
+ *\li  'pttl != NULL'.
  */
 
 isc_result_t
@@ -1479,8 +1471,8 @@ dns_message_response_minttl(dns_message_t *msg, dns_ttl_t *pttl);
  * section. If neither of these are set, return ISC_R_NOTFOUND.
  *
  * Requires:
- * \li   msg be a valid rendered message;
- * \li   'pttl != NULL'.
+ *\li  msg be a valid rendered message;
+ *\li  'pttl != NULL'.
  */
 
 void

diff --git a/lib/dns/message.c b/lib/dns/message.c
index 3b4757e5050d71a8dc74cf41968082879815f9ec..32a5976b775be4caace0122d2424200a27ae646a 100644 (file)
--- a/lib/dns/message.c
+++ b/lib/dns/message.c
@@ -2201,6 +2201,7 @@ dns_message_renderheader(dns_message_t *msg, isc_buffer_t *target) {
        isc_region_t r;
 
        REQUIRE(DNS_MESSAGE_VALID(msg));
+       REQUIRE(msg->buffer != NULL);
        REQUIRE(target != NULL);
 
        isc_buffer_availableregion(target, &r);
@@ -2530,7 +2531,7 @@ dns_message_addname(dns_message_t *msg, dns_name_t *name,
                    dns_section_t section) {
        REQUIRE(msg != NULL);
        REQUIRE(msg->from_to_wire == DNS_MESSAGE_INTENTRENDER);
-       REQUIRE(name != NULL);
+       REQUIRE(dns_name_isabsolute(name));
        REQUIRE(VALID_NAMED_SECTION(section));
 
        ISC_LIST_APPEND(msg->sections[section], name, link);
@@ -2541,7 +2542,7 @@ dns_message_removename(dns_message_t *msg, dns_name_t *name,
                       dns_section_t section) {
        REQUIRE(msg != NULL);
        REQUIRE(msg->from_to_wire == DNS_MESSAGE_INTENTRENDER);
-       REQUIRE(name != NULL);
+       REQUIRE(dns_name_isabsolute(name));
        REQUIRE(VALID_NAMED_SECTION(section));
 
        ISC_LIST_UNLINK(msg->sections[section], name, link);