OASIS Message Queuing Telemetry Transport (MQTT) TC

  • 1.  MQTT-145 - MAY vs may

    Posted 02-27-2014 15:35
    Issue MQTT-145 is about the use of may
    vs MAY in PRD1.  I have done a review of all the instances of the
    words "may" and "MAY" in the document.
    I would appreciate it if anyone who has
    had experience with may and MAY in other specifications could take a look
    at this and provide their views.

    The most pressing issue I found is the
    question about whether a server is required to support wild cards in topic
    filters or not (this was explicitly called out in MQTT-145), but I have
    listed a number of other things that need changing in Section 3 below.
    In Section 4 I have included a number of statements that are currently
    MAY, but which could be replaced by may (and in general you are supposed
    to  be sparing in your use of MAY).  I've also listed the places
    where "may" appears in non-normative text which appear to be
    describing normative choices.

    1. Introduction
    RFC 2119 says that the word "MAY"
    is meant to be used only for items that are truly optional.  It says
    "One vendor may choose to include the item because a particular marketplace
    requires it or because the vendor feels that it enhances the product while
    another vendor may omit the same item. An implementation which does not
    include a particular option MUST be prepared to interoperate with another
    implementation which does include the option, though perhaps with reduced
    functionality. In the same vein an implementation which does include a
    particular option MUST be prepared to interoperate with another implementation
    which does not include the option (except, of course, for the feature the
    option provides.)"
    - The best example I could find of "MAY"
    being used in this way is in line 849: "A Server MAY allow a Client
    to supply a ClientId that has a length of zero bytes."
    In contrast lower case "may"
    should be used when we are making an assertion about something that is
    permitted to happen within the protocol,
    - As an example, in line 1548 we say
    "Topic level separators may appear anywhere in a Topic Filter or Topic
    Name".  
    This kind of "may" is really
    making a kind of MUST statement in that an implementation is required to
    expect that Topic Filters or Names can have separators anywhere.  

    I notice that we also use lower case
    "may" in non-normative text, even where we are talking about
    items that are truly optional.

    2. Instances of may or MAY that are
    ok
     I found the following occurrences
    of lower-case "may" that look ok to me - none of them are meant
    to have the RFC2119 meaning
    34 "At least once", where messages
    are assured to arrive but duplicates may occur.
    47. A TC may approve a Working Draft
    66 - 82  Several occurrences of
    "may" in the standard OASIS text at the beginning of the document
    1394 Normal operation of the Client of
    Server may mean that stored state is lost or corrupted because of administrator
    action, hardware failure or software failure.
    1397 For example the server may determine
    that based on external knowledge, a message or messages can no longer be
    delivered to any current or future client.
    1404 For example, a user wishing to gather
    electricity meter readings may decide that they need to use QoS 1 messages
    because they need to protect the readings against loss over the network,
    however they may decide that the power supply is sufficiently reliable
    that the data in the Client and Server can be stored in volatile memory
    without too much risk of its loss.
    1548 Topic level separators may appear
    anywhere in a Topic Filter or Topic Name
    1666 Devices may be compromised
    1667 Data at rest in Clients and Servers
    may be accessible
    1668 Protocol behaviors may have side
    effects (e.g., 'timing attacks')
    1670 Communications may be intercepted,
    altered, re-routed or disclosed
    1688 In addition to technical security
    issues there may also be geographic...
    1696 An implementation may want to provide
    conformance with specific industry security standards such as NIST Cyber
    Security Framework [NISTCSF] ...
    1728 Implementations passing authentication
    data in clear text, obfuscating such data elements or requiring no authentication
    data should be aware this may give rise to Man-in-the-Middle and replay
    attacks.
    1758 An implementation may allow for
    authentication where the credentials are flowed in an Application Message
    from the Server to the Client.
    1780 An application may independently
    encrypt the contents of its Application Messages.
    1784 Client and Server implementations
    may provide encrypted storage for data at rest
    1801 Client and Server implementations
    using TLS [RFC5246] may choose to provide capabilities to check Certificate
    Revocation Lists (CRLs [RFC5280])...
    1855 Some MQTT implementations may make
    use of alternative secured tunnels (e.g. SSH) through the use of SOCKS.
    1858 implementations should be aware
    that SOCKS authentication may occur in plain-text
    1863 Implementers and solution designers
    may wish to consider security as a set of profiles
    1883 TLS [RFC5246] Client authentication
    may be used in addition to – or in place of – MQTT Client authentication
    as provided by the Username and Password fields.

    I found the following uses of "MAY"
    which seem to fit the description in RFC 2119:
    444 The data SHOULD NOT include encodings
    of the Unicode [Unicode63] code points listed below. If a receiver (Server
    or Client) receives a control packet containing any of them it MAY close
    the network  connection.
    679 If the protocol name is incorrect
    the Server MAY disconnect the Client, or it MAY continue processing the
    CONNECT packet in accordance with some other specification.
    842 The Server MAY restrict the ClientId
    it allows in terms of their lengths and the characters they contain
    849 A Server MAY allow a Client to supply
    a ClientId that has a length of zero bytes.
    888 Note that a Server MAY support multiple
    protocols (including earlier versions of this protocol) on the same TCP
    port or other network endpoint.
    898 The Server MAY check that the contents
    of the CONNECT Packet meet any further restrictions and MAY perform authentication
    and authorization checks.
    1022 In addition, the Server MAY deliver
    further copies of the message, one for each additional matching subscription
    and respecting the subscription's QoS in each case.
    1516 It MAY provide an administrative
    or other mechanism to allow one or more Topics to be treated as an "Unordered
    Topic"
    1594 MQTT Server implementations MAY
    define Topic Names that start with a leading $ character

    3. Instances which need fixing
    a) Topic Filter wild cards.  The
    question here is whether a server is required to support wildcards or not.
    At the moment there are two statements with lower case may (which implies
    that the server is required to support wild cards) and one with a MAY which
    implies that it does not have to support them. I think our intention is
    that a server is expected to support them, so the MAY in 1153 should be
    a may.
    240/1 A Topic Filter may include wildcard
    characters.
    1153 The Topic Filters are UTF-8 encoded
    strings, which MAY contain special wildcard characters to represent a set
    of topics, see Section 4.7.1.
    1541 A subscription’s Topic Filter may
    contain special wildcard characters, which allow you to subscribe to multiple
    topics at once.

    b) Dynamic Topics. As written this seems
    to require a Server to offer a choice of pre-defined or dynamic topics.
    I think this is a case where we could use some MAYs
    1650 The topic resource may be either
    predefined in the Server by an administrator or it may be dynamically created
    by the Server when it receives the first subscription or publication with
    that Topic Name. The Server may also use a security component to selectively
    authorize actions on the topic resource for a given Client.

    c) WebSocket.  I think this particular
    statement is ok as written, but issue mqtt-194 is about rewriting the whole
    section to include some MUSTs...
    1902 WebSocket binary frames are used.
    A single frame may contain multiple or partial MQTT Control Packets; they
    are not required to be aligned.

    d) The following occurrences of "MAY"
    are not meant to have the RFC2119 meaning so should be replaced by lower
    case may.
    526.  It SHOULD store the new QoS
    0 message as the new retained message for that topic, but MAY discard it
    at any time.
    816  Note that a Server MAY choose
    to disconnect a Client that it determines to be inactive or non-responsive
    at any time, regardless of the Keep Alive value provided by that Client.
    1178 The Server MAY start sending PUBLISH
    packets matching the Subscription before the Server sends the SUBACK Packet.
    1299 It MAY continue to deliver any existing
    messages buffered for delivery to the Client.
    1913 A single entity MAY conform as both
    an MQTT Client and MQTT Server implementation.

    4 Instances which are ok, but we could
    consider changing

    a) I found the following occurrences
    of "MAY" which could be interpreted to have RFC2119 meaning,
    but I think could be replaced with lower case may, as I don't think they
    directly affect interoperability
    708 It MAY also store QoS 0 messages
    that meet the same criteria.
    716 The Client MAY store QoS 0 messages
    for later transmission.
    722 The Server MAY store QoS 0 messages
    for which transmission to the Client has not yet been started.
    1483 Clients MAY resend SUBSCRIBE and
    UNSUBSCRIBE Packets on reconnect but are not REQUIRED to do this.

    b). Places where lower case "may"
    is used to describe an optional feature or behaviour in the following places,
    but this is text that is marked as non-normative:
    864 A Client implementation may provide
    a convenience method to generate a random ClientId.
    1723 Implementations can choose how to
    make use of the content of these fields. They may provide their own authentication
    mechanism, use an external authentication system such as LDAP [RFC4511]
    or OAuth [RFC6749] tokens, or leverage operating system authentication
    mechanisms.
    1743 An implementation may restrict access
    to Server resources based on information provided by the Client such as
    User Name, Client Identifier...
    1844 Servers may disconnect Clients and
    require them to re-authenticate with new credentials.
    I'm wondering whether some of these (e.g.
    1844) should be included in normative sections of the spec.

    Regards

    Peter Niblett
    Unless stated otherwise above:
    IBM United Kingdom Limited - Registered in England and Wales with number
    741598.
    Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
    3AU