Subject: [Isms] new wording for server side counters and establishing a session

From: Wes Hardaker <[email-masked]>
Date: Fri, 29 Jan 2010 17:23:40 -0800

Ok, to support the goals discussed recently:

  1) renames everything to Jurgen's proposed names
  2) puts text in the incoming message handling that says when to
     increment the server side handling
  3) rearranges the "establishing a session" section to clearly indicate
     that openSession() is for the client and split the server side into
     a separate sub section.
  4) removed the serverSessionOpenErrors counter entirely since it was
     basically impossible to say when it happens since it would
     generally happen long before the TLSTM got to handling packets.

The resulting changed text pieces are below.  I'll want to read them
once more before I consider them done when my head is fresh again.  I'll
publish a new copy Monday-ish.

Counters:

  snmpTlstmSession           OBJECT IDENTIFIER ::= { tlstmObjects 1 }

  snmpTlstmSessionOpens  OBJECT-TYPE
      SYNTAX       Counter32
      MAX-ACCESS   read-only
      STATUS       current
      DESCRIPTION
         "The number of times an openSession() request has been
         executed as an (D)TLS client, whether it succeeded or failed."
      ::= { snmpTlstmSession 1 }

  snmpTlstmSessionClientCloses  OBJECT-TYPE
      SYNTAX       Counter32
      MAX-ACCESS   read-only
      STATUS       current
      DESCRIPTION
          "The number of times a closeSession() request has been
          executed as an (D)TLS client, whether it succeeded or failed."
      ::= { snmpTlstmSession 2 }

  snmpTlstmSessionOpenErrors  OBJECT-TYPE
      SYNTAX       Counter32
      MAX-ACCESS   read-only
      STATUS       current
      DESCRIPTION
          "The number of times an openSession() request failed to open a
          session as a (D)TLS client, for any reason."
      ::= { snmpTlstmSession 3 }

  snmpTlstmSessionAccepts  OBJECT-TYPE
      SYNTAX       Counter32
      MAX-ACCESS   read-only
      STATUS       current
      DESCRIPTION
         "The number of times a server has accepted a (D)TLS session and
         at least one SNMP message has been accepted through it."
      ::= { snmpTlstmSession 4 }

  snmpTlstmSessionServerCloses  OBJECT-TYPE
      SYNTAX       Counter32
      MAX-ACCESS   read-only
      STATUS       current
      DESCRIPTION
          "The number of times a closeSession() request has been
          executed as an (D)TLS server, whether it succeeded or failed."
      ::= { snmpTlstmSession 5 }

Incoming processing:

  5.1.2.  Transport Processing for Incoming SNMP Messages

     The procedures in this section describe how the TLS Transport Model
     should process messages that have already been properly extracted
     from the (D)TLS stream.  Note that care must be taken when processing
     messages originating from either TLS or DTLS to ensure they're
     complete and single.  For example, multiple SNMP messages can be
     passed through a single DTLS message and partial SNMP messages may be
     received from a TLS stream.  These steps describe the processing of a
     singular SNMP message after it has been delivered from the (D)TLS
     stream.

     1)  Determine the tlstmSessionID for the incoming message.  The
         tlstmSessionID MUST be a unique session identifier for this
         (D)TLS connection.  The contents and format of this identifier
         are implementation-dependent as long as it is unique to the
         session.  A session identifier MUST NOT be reused until all
         references to it are no longer in use.  The tmSessionID is equal
         to the tlstmSessionID discussed in Section 5.1.1. tmSessionID
         refers to the session identifier when stored in the
         tmStateReference and tlstmSessionID refers to the session
         identifier when stored in the LCD.  They MUST always be equal
         when processing a given session's traffic.

         If this is the first message received through this session and
         the session does not have an assigned tlstmSessionID yet then the
         snmpTlstmSessionAccepts counter is incremented and a
         tlstmSessionID for the session is created.  This will only happen
         on the server side of a connection because a client would have
         already assigned a tlstmSessionID during the openSession()
         invocation.  Implementations may have performed the procedures
         described in Section 5.3.2 prior to this point or they may
         perform them now, but the procedures described in Section 5.3.2
         MUST be performed before continuing beyond this point.

     2)  Create a tmStateReference cache for the subsequent reference and
         assign the following values within it:

         tmTransportDomain  = snmpTLSTCPDomain, snmpDTLSUDPDomain or
            snmpDTLSSCTPDomain as appropriate.

         tmTransportAddress  = The address the message originated from.

         tmSecurityLevel  = The derived tmSecurityLevel for the session,
            as discussed in Section 3.1.2 and Section 5.3.

         tmSecurityName  = The derived tmSecurityName for the session as
            discussed in Section 5.3.  This value MUST be constant during
            the lifetime of the (D)TLS session.

         tmSessionID  = The tlstmSessionID described in step 1 above.

     3)  The incomingMessage and incomingMessageLength are assigned values
         from the (D)TLS processing.

     4)  The TLS Transport Model passes the transportDomain,
         transportAddress, incomingMessage, and incomingMessageLength to
         the Dispatcher using the receiveMessage ASI:

         statusInformation =
         receiveMessage(
         IN   transportDomain     -- snmpTLSTCPDomain, snmpDTLSUDPDomain,
                                  -- or snmpDTLSSCTPDomain
         IN   transportAddress    -- address for the received message
         IN   incomingMessage        -- the whole SNMP message from (D)TLS
         IN   incomingMessageLength  -- the length of the SNMP message
         IN   tmStateReference    -- transport info
          )

Establishing Section:

  5.3.  Establishing or Accepting a Session

     Establishing a (D)TLS session as either a client or a server requires
     slightly different processing.  The following two sections describe
     the necessary processing steps.

  5.3.1.  Establishing a Session as a Client

     The TLS Transport Model provides the following primitive for use by a
     client to establish a new (D)TLS session:

     statusInformation =           -- errorIndication or success
     openSession(
     IN   tmStateReference         -- transport information to be used
     OUT  tmStateReference         -- transport information to be used
     IN   maxMessageSize           -- of the sending SNMP entity
     )

     The following describes the procedure to follow when establishing a
     SNMP over (D)TLS session between SNMP engines for exchanging SNMP
     messages.  This process is followed by any SNMP client's engine when
     establishing a session for subsequent use.

     This MAY be done automatically for an SNMP application that initiates
     a transaction, such as a command generator, a notification
     originator, or a proxy forwarder.

     1)  The snmpTlstmSessionOpens counter is incremented.

     2)  The client selects the appropriate certificate and cipher_suites
         for the key agreement based on the tmSecurityName and the
         tmRequestedSecurityLevel for the session.  For sessions being
         established as a result of a SNMP-TARGET-MIB based operation, the
         certificate will potentially have been identified via the
         tlstmParamsTable mapping and the cipher_suites will have to be
         taken from system-wide or implementation-specific configuration.
         Otherwise, the certificate and appropriate cipher_suites will
         need to be passed to the openSession() ASI as supplemental
         information or configured through an implementation-dependent
         mechanism.  It is also implementation-dependent and possibly
         policy-dependent how tmRequestedSecurityLevel will be used to
         influence the security capabilities provided by the (D)TLS

         session.  However this is done, the security capabilities
         provided by (D)TLS MUST be at least as high as the level of
         security indicated by the tmRequestedSecurityLevel parameter.
         The actual security level of the session is reported in the
         tmStateReference cache as tmSecurityLevel.  For (D)TLS to provide
         strong authentication, each principal acting as a command
         generator SHOULD have its own certificate.

     3)  Using the destTransportDomain and destTransportAddress values,
         the client will initiate the (D)TLS handshake protocol to
         establish session keys for message integrity and encryption.

         If the attempt to establish a session is unsuccessful, then
         snmpTlstmSessionOpenErrors is incremented, an error indication is
         returned, and processing stops.  If the session failed to open
         because the presented server certificate was unknown or invalid
         then the snmpTlstmSessionUnknownServerCertificate or
         snmpTlstmSessionInvalidServerCertificates MUST be incremented and
         a tlstmServerCertificateUnknown or tlstmServerInvalidCertificate
         notification SHOULD be sent as appropriate.  Reasons for server
         certificate invalidation includes, but is not limited to,
         cryptographic validation failures and an unexpected presented
         certificate identity.

     4)  The (D)TLS client MUST then verify that the (D)TLS server's
         presented certificate is the expected certificate.  The (D)TLS
         client MUST NOT transmit SNMP messages until the server
         certificate has been authenticated and the client certificate has
         been transmitted.

         If the connection is being established from configuration based
         on SNMP-TARGET-MIB configuration then the procedures in the
         tlstmAddrTable DESCRIPTION clause should be followed to determine
         if the presented identity matches the expectations of the
         configuration.  Validation procedures (like the path validation
         procedures defined in [RFC5280] or through the use of
         fingerprints as defined by the tlstmAddrServerIdentity column)
         MUST be followed.  If a server identity name has been configured
         in the tlstmAddrServerIdentity column then this reference
         identity must be compared against the presented identity (for
         example using procedures described in
         [I-D.saintandre-tls-server-id-check]).

         If the connection is being established for reasons other than
         configuration found in the SNMP-TARGET-MIB then configuration and
         procedures outside the scope of this document should be followed.

     5)  (D)TLS provides assurance that the authenticated identity has
         been signed by a trusted configured certificate authority.  If
         verification of the server's certificate fails in any way (for
         example because of failures in cryptographic verification or the
         presented identity did not match the expected named entity) then
         the session establishment MUST fail, the
         snmpTlstmSessionInvalidServerCertificates object is incremented.
         If the session can not be opened for any reason at all, including
         cryptographic verification failures, then the
         snmpTlstmSessionOpenErrors counter is incremented and processing
         stops.

     6)  The TLSTM-specific session identifier (tlstmSessionID) is set in
         the tmSessionID of the tmStateReference passed to the TLS
         Transport Model to indicate that the session has been established
         successfully and to point to a specific (D)TLS session for future
         use.  The tlstmSessionID is also stored in the LCD for later
         lookup during processing of incoming messages (Section 5.1.2).

  5.3.2.  Accepting a Session as a Server

     A (D)TLS server should accept new session connections from any client
     that it is able to verify the client's credentials for.  This is done
     by authenticating the client's presented certificate through a
     certificate path validation process (e.g.  [RFC5280]) or through
     certificate fingerprint verification using fingerprints configure in
     the tlstmCertToTSNTable.  Afterward the server will determine the
     identity of the remote entity using the following procedures.

     The (D)TLS server identifies the authenticated identity from the
     (D)TLS client's principal certificate using configuration information
     from the tlstmCertToTSNTable mapping table.  The (D)TLS server MUST
     request and expect a certificate from the client and MUST NOT accept
     SNMP messages over the (D)TLS session until the client has sent a
     certificate and it has been authenticated.  The resulting derived
     tmSecurityName is recorded in the tmStateReference cache as
     tmSecurityName.  The details of the lookup process are fully
     described in the DESCRIPTION clause of the tlstmCertToTSNTable MIB
     object.  If any verification fails in any way (for example because of
     failures in cryptographic verification or because of the lack of an
     appropriate row in the tlstmCertToTSNTable) then the session
     establishment MUST fail, the
     snmpTlstmSessionInvalidClientCertificates object is incremented.  If
     the session can not be opened for any reason at all, including
     cryptographic verification failures, then the
     snmpTlstmSessionOpenErrors counter is incremented and processing
     stops.

     Servers that wish to support multiple principals at a particular port
     SHOULD make use of a (D)TLS extension that allows server-side
     principal selection like the Server Name Indication extension defined
     in Section 3.1 of [RFC4366].  Supporting this will allow, for
     example, sending notifications to a specific principal at a given
     TCP, UDP or SCTP port.

-- 
Wes Hardaker
Cobham Analytic Solutions