Subject: RE: MIB doctor review of draft-ietf-atommib-rfc2496bis-02.txt

From: "Lam, Hing-Kam (Kam)" <[email-masked]>
Date: Thu, 29 May 2003 15:34:47 -0400

Hi,

In Mike's suggested changes for Section 6, there are typos (from cut-and-paste).

> 6.) Security Considerations Section -- the part that deals with the
... snipped
>    The readable objects in this MIB module (i.e., the objects with a
>    MAX-ACCESS other than not-accessible) may be considered sensitive
>    in some environments since, collectively, they provide extensive
>    information about the performance of interfaces in DS1/E1/DS2/E2
                                                        ^^^^^^^^^^^^^
It should be DS3/E3

Regards,
Kam

> -----Original Message-----
> From: C. M. Heard [mailto:[email-masked]]
> Sent: Sunday, May 18, 2003 4:40 PM
> To: AToM MIB Working Group
> Cc: Orly Nicklass; Lam, Hing-Kam (Kam); Faye Ly; Erik Nordmark; Thomas
> Narten; Wijnen, Bert (Bert)
> Subject: MIB doctor review of draft-ietf-atommib-rfc2496bis-02.txt
> 
> 
> AToM MIB folks,
> 
> This message contains the results of a MIB doctor review of the
> DS3-MIB that I volunteered to do in an off-line e-mail exchange
> with the editor, chairs, and ADs.  The version reviewed is the
> one that is in
> 
> http://www.ietf.org/internet-drafts/draft-ietf-atommib-rfc2496
> bis-02.txt
> 
> The comments below follow the MIB review checklist from Appendix A
> of <draft-ietf-ops-mib-review-guidelines-01.txt>.
> 
> 1.) I-D Boilerplate -- OK
> 
> 2.) Abstract -- the following things need to be corrected:
> 
> (a) in the first line:  s/an experimental portion/a portion/
> 
> (b) citations are not allowed in the abstract (see Section 2 of
> http://www.ietf.org/ID-nits.html), and anyway the RFC numbers
> that are cited will be no longer be current by the time this
> document is published.  I suggest that the last sentence of the
> first paragraph be changed to:
> 
>    This document is a companion to the documents that define
>    managed objects for the DS0, DS1/E1/DS2/E2, and Synchronous
>    Optical Network/Synchronous Digital Hierarchy (SONET/SDH)
>    interface types.
> 
> It would be acceptable to put in RFC numbers (but not citations) if
> an RFC Editor note also is included note to deal with the fact that
> they will need to be updated by the time the document is published.
> (Note: in my opinion the sentence above would read better if the
> acronym SONET/SDH was not expanded, but current RFC Editor rules
> require that acronyms in the abstract be expanded on first use
> unless they are likely to be known to all IETF members.)
> 
> (c) the second paragraph is obsolete and the third paragraph is
> untrue, so please delete them both.
> 
> 3.) MIB Boilerplate -- the standard heading for the boilerplate
> section is "The Internet-Standard Management Framework" ... so
> please s/SNMP/Internet-Standard/ in the heading of Section 1.
> 
> 4.) IPR Notices -- OK (required boilerplate is present;  no claims
> are noted;  no change from RFC 2496).
> 
> 5.) References -- the following things require attention:
> 
> (a) several of the references do not appear to be used, either
> in the text, in the IMPORTS statement, or in a REFERENCE clause.
> Those are: [RFC3411], [RFC3412], [RFC3413], [RFC3414], [RFC3415],
> [RFC1155], [RFC1212], [RFC1215], [RFC1157], and [RFC1901].  Note
> that earlier versions of these documents used to be referenced
> by the MIB boilerplate, but that is no longer the case.
> 
> (b) the following references are listed as informative, but I
> believe that they should be listed as normative:
> 
> 
> [ANSI-T1.102]       referenced in MIB module (line type value)
> [ANSI-T1.107]       referenced in MIB module (line type values)
> [ANSI-T1.107a]      referenced in MIB module (line type values)
> [ANSI-T1.404]       cited as source document for DS3 definitions
> [ANSI-T1.231]       cited as source document for DS3 error
>                     condition terminology (also mentioned in many
>                     parameter definitions, but those definitions
>                     are self-contained and implementors are
>                     instructed to use the definitions in the MIB
>                     document instead of the ones in T1.231)
> [CCITT-G.751]       referenced in MIB module (line type value)
> [ETSI-T/NA(91)18]   referenced in MIB module (line type value)
> [RFC2493]           referenced in MIB module IMPORTS statement
>                     (PerfHist-TC-MIB).  Note: this reference should
>                     point to the forthcoming update of RFC 2493
>                     (the RFC number is TBD, the approved draft
>                     is <draft-ietf-atommib-rfc2493bis-01.txt>;
>                     suggest to change the tag to [RFC2493bis] and
>                     list the I-D name;  the RFC Editor will fill
>                     in the RFC number when it is assigned).
> [ITU-T-M.1400]      cited in definition of circuit identifier (both
>                     in the text and in MIB module REFERENCE clause)
> 
> (c) there are two places in the document that refer to RFC 1213,
> one in the DESCRIPTION clause of the deprecated object dsx3IfIndex
> and one in Appendix A, which describes the historical (RFC 1407)
> usage of dsx3LineIndex/dsx3IfIndex.  It should therefore be listed
> as an informative reference.  So also should RFC 1407 itself.
> 
> (d) the following informative references should probably point to
> the forthcoming updates:
> 
> [RFC2495]           the RFC number is TBD, the unapproved draft
>                     is <draft-ietf-atommib-rfc2495bis-02.txt>
> 
> [RFC2558]           the RFC number is TBD, the approved draft
>                     is <draft-ietf-atommib-rfc2558bis-01.txt>
> 
> You may want to handle these with an RFC Editor note at the end of
> the document, as was done in <draft-ietf-atommib-rfc2493bis-01.txt>
> 
> 6.) Security Considerations Section -- the part that deals with the
> vulnerabilities of writeable objects does not list some of the
> relevant objects and in also reads a bit awkwardly.   I therefore
> recommend a rewrite of that part.  The part that deals with the
> vulnerabilities of readable objects is missing;  as noted in Section
> 3.6 of <draft-ietf-ops-mib-review-guidelines-01.txt>, that's not
> allowed, and if there really are no vulnerabilities then there must
> be an explicit statement to that effect.  I don't think that would
> be entirely appropriate in this case and would instead suggest
> borrowing the language from the recently-approved SONET-MIB draft
> <draft-ietf-atommib-rfc2558bis-01.txt>.  The specific wording
> changes that I suggest are to replace everything up to (but not
> including) the last three paragraphs with this:
> 
>    There are a number of management objects defined in this MIB
>    module with a MAX-ACCESS clause of read-write.  Such objects may
>    be considered sensitive or vulnerable in some network environments.
>    The support for SET operations in a non-secure environment without
>    proper protection can have a negative effect on network operations.
>    The specific the objects and their sensitivities/vulnerabilities
>    are as follows.
> 
>    Setting the following objects to incorrect values may result in
>    traffic interruptions:
> 
>       dsx3LineType
>       dsx3LineCoding
>       dsx3SendCode
>       dsx3LoopbackConfig
>       dsx3TransmitClockSource
>       dsx3LineLength
>       dsx3Channelization
>       dsx3Ds1ForRemoteLoop
> 
>    In the case of dsx3LineType, for example, both ends of a 
> DS3/E3 must
>    have the same value in order for traffic to flow.  In the case of
>    dsx3SendCode and dsx3LoopbackConfig, for another example, 
> traffic may
>    stop transmitting when particular loopbacks are applied.
> 
>    Setting the following objects to an incorrect value will result in
>    the remote end receiving an incorrect Path Identification message,
>    which may result in a connectivity alarm:
> 
>       dsx3FarEndEquipCode
>       dsx3FarEndLocationIDCode
>       dsx3FarEndFrameIDCode
>       dsx3FarEndUnitCode
>       dsx3FarEndFacilityIDCode
> 
>    Setting the following object to an incorrect value will 
> not harm the
>    traffic, but it may cause a circuit to be mis-identified 
> and thereby
>    create difficulties for service personnel when attempting to
>    troubleshoot a problem:
> 
>       dsx3CircuitIdentifier
> 
>    Setting the following object can cause an increase in the number of
>    traps received by the network management station:
> 
>       dsx3LineStatusChangeTrapEnable
> 
>    The readable objects in this MIB module (i.e., the objects with a
>    MAX-ACCESS other than not-accessible) may be considered sensitive
>    in some environments since, collectively, they provide extensive
>    information about the performance of interfaces in DS1/E1/DS2/E2
>    equipment or networks and can reveal some aspects of their
>    configuration.  In such environments it is important to control
>    even GET and NOTIFY access to these objects and possibly to
>    encrypt the values of these objects when sending them over the
>    network via SNMP.
> 
> The last three paragraphs (starting with "SNMP versions prior to
> SNMPv3") would follow at this point.
> 
> NOTE TO DOCUMENT EDITOR:  PLEASE VERIFY that the text proposed above
> accurately describes what can happen when dsx3FarEndEquipCode and
> kin are incorrectly modified.  I have assumed that it works like the
> Path Trace message in SONET.  If that is not the case, then please
> make corrections as needed before incorporating the changed into
> the document.
> 
> 7.) IANA Considerations Section -- OK (none present and none
> required).
> 
> 8.) Copyright notices -- there is no full copyright notice as
> required by RFC 2026 sec 10.4(C), nor is there a copyright
> notice in the MODULE-IDENTITY DESCRIPTION clause as required
> by http://www.ietf.org/IESG/STATEMENTS/MIB-COPYRIGHT.txt
> (see also <draft-ietf-ops-mib-review-guidelines-01.txt>
> Section 3.8).  Note:  specific fixes to the MODULE-IDENTITY
> DESCRIPTION clause will be included in the comments under
> item #11 below.
> 
> 9.) MIB compilation -- a copy of the smidiff report from the e-mail
> robot at <[email-masked]> is attached.  Note that it shows
> both the smilint warnings for the old version of the MIB module
> (DS3-MIB-9808012130Z, extracted from RFC 2496) and the new version
> (DS3-MIB-200305040000Z, extracted from the 2496bis draft) as well
> as the differences between the two.
> 
> All of the smilint warnings in the new module are inherited from the
> previous version.  I have audited all of them, and in most cases no
> action is required.  The "use Integer32 instead of INTEGER" warnings
> are all triggered by objects which use INTEGER with a subrange, and
> that practice is acceptable under the guidelines in Section 4.6.1.1
> of <draft-ietf-ops-mib-review-guidelines-01.txt>.  Hence these
> warnings can be safely ignored.  The "index element ... should be
> not-accessible" warnings are a result of the MIB module having been
> converted from SMIv1 which required index objects to be accessible.
> The only action recommended for these is to add an ASN.1 comment to
> each read-only index object stating why its MAX-ACCESS value is
> read-only.  Details can be found in the comments under item #11
> below.  The "implicit node definition" warning is a complaint about
> a particular style convention and does not indicate a problem.  The
> unreferenced group warning for deprecated group `ds3DeprecatedGroup'
> is likewise not a problem, since it is reasonable for a deprecated
> group of deprecated objects to be unreferenced by any compliance
> statement.  The unreferenced group warning for current group
> `ds3NearEndOptionalTrapGroup' simply indicates that the group (as
> its name indicates) is optional.  In this reviewer's opinion the
> intent is sufficiently clear that there is no need to enforce the
> recommendation in <draft-ietf-ops-mib-review-guidelines-01.txt>
> Section 4.8 to mention this group in a GROUP clause.  (Note,
> however, that when it comes time to advance the specification it
> will be necessary either to provide evidence that this group is
> present in two implementations or else it must be deprecated.)
> 
> I have likewise audited all of the diagnostics from smidiff, and I
> find that all of the "warning:" and "info:" messages are for changes
> that are both correct and intended and may be safely ignored.
> However, both of the level 3 diagnostic messages indicate problems.
> This one
> 
> DS3-MIB-200305040000Z:1406 [3] {range-changed} range of type used in
> `dsx3FracIndex' changed from `(1..2147483647)' to `(0..2147483647)'
> 
> would be acceptable _if_ it indicated that the change was made to
> `dsx3FracIfIndex' because that would correct a bug in the original
> definition (the range and DESCRIPTION clause did not agree).  It
> appears, however, that the wrong object was changed by mistake.
> This is further discussed in the comments under item #11 below.
> 
> The other level 3 diagnostic message, i.e.,
> 
> DS3-MIB-9808012130Z:32 [3] {revision-removed} revision
> `1998-08-01 21:30' removed
> 
> also points to a problem that needs to be corrected.  It is present
> because the revised MODULE-IDENTITY invocation has no
> REVISION/DESCRIPTION pair for the previous version of the MIB
> module.  In fact the guidelines in Section 4.5 of
> <draft-ietf-ops-mib-review-guidelines-01.txt> now require a
> REVISION/DESCRIPTION pair for every published version of the
> MIB module, which would include RFC 1407 in this case.  A detailed
> correction for this is proposed in the comments under #11 below.
> 
> With the exception of the dsx3FracIndex/dsx3FracIfIndex issue noted
> above, it has also been verified that the change log in Section 1.1
> accurately summarizes all significant changes reported by smidiff.
> 
> 10.) Other issues (e.g., stuff in http://www.ietf.org/ID-nits.html
> that is not covered above) -- there are some lines that exceed 72
> characters in Section 1.1 and in the MIB module itself (although the
> latter will go away if the module indentation is reduced from 10
> spaces down to 3).  The last paragraph on page 12 (beginning with
> "In any case, a linkDown trap") and the next paragraph that starts
> on page 13 (beginning with "According to ANSI T1.231") are
> incorrectly indented;  they should be aligned with the normal text
> (i.e., indented by 3 spaces only).  Readability would be improved if
> a page break is inserted before the start of the first table in
> Appendix A and before the start of Appendix B.  It is also suggested
> to put page breaks before the start of the figure in Appendix B to
> ensure that it resides on a single page.  Finally, there are a
> number of typos, which are listed separately in the first of the
> two attached context diffs.
> 
> 11.) Technical content -- here are the comments on the content of
> the MIB module.  Note:  since this is a revision of a MIB module
> that has been widely implemented, I have not attempted to do an
> ab-initio technical review of the whole thing;  I have instead
> concentrated on the stuff that has changed.
> 
> (a) In MODULE-IDENTITY invocation: (i) the CONTACT-INFO clause MUST
> have the WG mailing list info and SHOULD have a pointer to the WG
> charter page;  (ii) there MUST be a copyright notice at the end of
> DESCRIPTION clause;  and (ii) there MUST be a REVISION/DESCRIPTION
> pair for each published version of the MIB module (see sections 3.8
> and 4.5 of <draft-ietf-ops-mib-review-guidelines-01.txt>).  Proposed
> text to fix these omissions is included in the second of the two
> context diffs attached to this message.  Note that the revision date
> for the RFC 2496 version is taken from the LAST-UPDATED clause in
> that version of the MIB module, while the revision date for the
> RFC 1407 version is taken from time stamp on the file at the RFC
> Editor's web site.  Note that the proposed revision clause for the
> latest version of the MIB module does not have a detailed list of
> changes because one is already present in Section 1.1 of the draft;
> that could be added (or the contents of Section 1.1 moved there) at
> the editor's discretion.
> 
> For sake of precision, the MODULE-IDENTITY invocation with the
> proposed revisions included is reproduced below.
> 
> ds3 MODULE-IDENTITY
>     LAST-UPDATED "200305040000Z"
>     ORGANIZATION "IETF AToM MIB Working Group"
>     CONTACT-INFO
>       "WG charter:
>          http://www.ietf.org/html.charters/atommib-charter.html
> 
>        Mailing Lists:
>          General Discussion: [email-masked]
>          To Subscribe: [email-masked]
> 
>        Editor: Orly Nicklass
> 
>        Postal: RAD Data Communications, Ltd.
>                Ziv Tower, 24 Roul Walenberg
>                Tel Aviv, Israel, 69719
> 
>                Tel: +9723 765 9969
>        E-mail: [email-masked]"
> 
>     DESCRIPTION
>          "The is the MIB module that describes
>           DS3 and E3 interfaces objects.
> 
>           Copyright (c) The Internet Society (2003).  This
>           version of this MIB module is part of RFC yyyy;
>           see the RFC itself for full legal notices."
> -- RFC Ed.: replace yyyy with actual RFC number & remove this notice
> 
>     REVISION "200305040000Z"
>     DESCRIPTION
>          "The RFC yyyy version of this MIB module."
> -- RFC Ed.: replace yyyy with actual RFC number & remove this notice
> 
>     REVISION "199808012130Z"
>     DESCRIPTION
>          "The RFC 2496 version of this MIB module."
> 
>     REVISION "199301252028Z"
>     DESCRIPTION
>          "Initial version, published as RFC 1407."
> 
>     ::= { transmission 30 }
> 
> (b) As noted in #9 above, this MIB module contains a number of
> read-only index columns that are a legacy of its origin as an
> SMIv1 MIB module.  Although it is not strictly required, it is
> recommended to add ASN.1 comments to the definitions of these
> objects explaining why they are read-only.  For example:
> 
> dsx3LineIndex OBJECT-TYPE
>      SYNTAX  InterfaceIndex
>      MAX-ACCESS  read-only  -- read-only since originally an
>                             -- SMIv1 index
>      STATUS  current
>      DESCRIPTION
>             [ ... ]
> 
> with similar changes for dsx3CurrentIndex, dsx3IntervalIndex,
> dsx3IntervalNumber, dsx3TotalIndex, dsx3FarEndLineIndex,
> dsx3FarEndCurrentIndex, dsx3FarEndIntervalIndex,
> dsx3FarEndIntervalNumber, dsx3FarEndTotalIndex, dsx3FracIndex, and
> dsx3FracNumber.  Complete details of the proposed changes
> are included in the context diff.
> 
> (c) In the definition of Dsx3FarEndConfigEntry fix formatting:
> s/ dsx3FarEndLineIndex/dsx3FarEndLineIndex /
> 
> (d) As noted in (9) above, the SYNTAX value of dsx3FracIndex was
> changed instead of that of dsx3FracIfIndex as stated in the
> draft's change log.  It is clear from reading the DESCRIPTION
> clauses of the two objects that dsx3FracIfIndex is the one that
> should have been changed.  Thus, the next version of the draft
> must change the SYNTAX value of dsx3FracIndex back to
> INTEGER (1..'7fffffff'h) and must change to SYNTAX value of
> dsx3FracIfIndex to (0..'7fffffff'h) or (at the editor's
> discretion) to InterfaceIndexOrZero.  If the latter is done, then
> the InterfaceIndexOrZero TC would need to be imported from IF-MIB.
> (It is recommended that the same course of action be chosen for
> this object and for dsx1FracIfIndex in the DS1-MIB.)  The
> context diff shows the version without InterfaceIndexOrZero.
> 
> (d) In the ASN.1 comment preceding the definition of ds3Traps:
> s/ -- Ds3 TRAPS/-- DS3 TRAPS/
> 
> This concludes the DS3-MIB review comments.
> 
> Mike Heard
>

---

From: "C. M. Heard" <[email-masked]>
Date: Thu, 29 May 2003 12:50:27 -0700 (PDT)

> >    information about the performance of interfaces in DS1/E1/DS2/E2

Thanks for catching this.

//cmh