Draft 01                                                        James Morris
                                                           December 30, 2001
                                                             
               Security Context Mapping Protocol, Version 1


Table of Contents

  1.  Introduction
  2.  Protocol Overview
  3.  Labeling
  4.  Protection
  5.  Transport
  6.  Message Formats
    6.1  Base Message
    6.2  Map Request
    6.3  Map Response
    6.4  Error Response
  7.  Messaging scenarios
    7.1  Successful Map Request/Response
    7.2  Error Response to Map Request
    7.3  Error Response to Map Response
  8.  Error handling
  9.  Security Considerations
  10. References
  11. Author
  12. Acknowledgments
  13. Copyright


1. Introduction

  This document describes version 1 of the Security Context Mapping Protocol
  (SCMP).
  
  SCMP is a component of Selopt [1], an implementation of labeled IPv4
  networking for NSA Security Enhanced Linux (SELinux) [2].  SCMP provides
  a simple, UDP-based mechanism for mapping Security ID (SID) labels on
  received packets to locally significant SIDs.
  
  SCMP also provides support for policy change through the use of policy
  serial numbers associated with each packet and SCMP message.
  
  As SCMP is a security component, simplicity is a predominant design
  goal.


2. Protocol Overview
   
  The role of SCMP is to provide a mechanism for mapping remote SIDs
  to local SIDs, as SIDs only have local significance.  This is achieved
  via out of band lookups.
  
  SCMP is a peer to peer protocol, where each peer can be simultaneously
  an initiator and receiver.  It utilizes three types of messages:
  
    o Map Request    - Request security contexts from a peer for a set of
                       remote SIDs.
                     
    o Map Response   - Response to Map Request, with a map of security
                       contexts and remote SIDs.
                     
    o Error Response - Response to Map Request or Map Response, indicating
                       that an error during message processing.

  Typically, SCMP messaging is performed by a userspace daemon.  Map
  Request messages are triggered by the kernel when it needs to map
  SID labels on received packets.  The userspace daemon essentially
  proxies these requests over SCMP to the originating peer.  When the
  peer responds with Map Response messages, the userspace daemon maps
  the remote security contexts to local SIDs and passes the results back
  to the kernel.


3. Labeling

  SCMP messages are not explicitly labeled, as this would cause recursive
  lookups.  Instead, they are implicitly labeled and bypass most of the
  Selopt labeling mechanisms.


4. Protection

  SCMP messages must be protected along with all other labeled traffic.
  Protection requirements are discussed in [1].
  
  Typically, this protection will be provided by IPsec [3].
  

5. Transport

  SCMP messages use UDP for transport on port 40000.
  

6. Message Formats

  All messages share the Base message as the first component, followed by
  an extension message.
  
  All integer fields longer than one byte must be transmitted in network
  byte order.
  

6.1 Base Message

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !    Version    !      Type     !         Total Length          !
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !                         Peer Address                          |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !                        Sequence Number                        !
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !                      Policy Serial Number                     !
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    
  Version: 8 bits.
  
    The SCMP version number, must be set to 1.
    
  Type: 8 bits.
  
    The type of message extension following the base message.
    
  Total Length: 16 bits.
  
    The total length of the message in octets.
    
  Peer Address: 32 bits.
  
    IPv4 address of the peer associated with the payload.  May be different
    to the source address of the packet for multi-homed or virtual peers.
    
  Sequence Number: 32 bits.
  
    Per-message sequence number, set by sender.  The receiver echos this
    in any response message to a specific request message.
    
  Policy Serial Number: 32 bits.

    The serial number of the local security policy which was current when
    this message was generated.  


6.2 Map Request Extension

  Description: Request security context mappings for given SIDs.
  Type: 2

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !            Records            !            Reserved           |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !                      Security Identifiers                     !
    ~                                                               ~
    !                                                               !
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  Records: 16 bits.
  
    The number of SIDs present in the request, which must be between
    one and three inclusive.
    
  Reserved: 16 bits.
  
    Must be zero.
    
  Security Identifiers: 32 bits each.
  
    The remote SIDs which need to be mapped.
    

6.3 Map Response Extension

  Description: Response to Map Request - SID to context mappings.
  Type: 3

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !            Records            !            Reserved           |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

    Map Entries:
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !                      Security Identifier                      !
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !        Context Length         !            Reserved           |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !                        Security Context                       !
    ~                                                               ~
    !                                                     +-+-+-+-+-+
    !                                                     ! Padding !
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  Records: 16 bits.
  
    The number of mappings present in the request, which must be between
    one and three inclusive.
    
  Reserved: 16 bits.
  
    Must be zero.

  Map entries:
  
    Each map entry consists of:
    
      Security Identifier: 32 bits.
      
        The SID associated with the security context in this map entry.
        
      Context Length: 16 bits.
      
        The length of the associated security context in octets, including
        padding, to a maximum value of 8192.
        
      Security Context: variable.
      
        The ASCII text representation of the security context associated with
        the remote SID in this entry.
        
      Padding: variable.
      
        Zero padding appended to the right of the Security Context field
        such that each Map Entry is 32-bit aligned.


6.4 Error Response Extension

  Description: Report error when processing Map Request or Map Response
               messages.
  Type: 4

  After the base header, the Error Response extension includes a copy of the
  original SCMP header.
  
  The following fields are then appended:
  
    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    !         Error Code            !            Pointer            |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  
  Error Code: 16 bits.

    Numeric code describing the type of error which caused the Error Response
    message to be generated.  Must be one of the following values:
    
      +---+-----------------------------------------------------+
      | 0 | Unspecified error.                                  |
      +---+-----------------------------------------------------+
      | 1 | Invalid message length.                             | 
      +---+-----------------------------------------------------+
      | 2 | Invalid payload address.                            |
      +---+-----------------------------------------------------+
      | 3 | Invalid SCMP version.                               |
      +---+-----------------------------------------------------+
      | 4 | Invalid message type.                               |
      +---+-----------------------------------------------------+
      | 5 | Local system error.                                 |
      +---+-----------------------------------------------------+
      | 6 | Local application error.                            |
      +---+-----------------------------------------------------+
      | 7 | Invalid number of records in payload.               |
      +---+-----------------------------------------------------+
      | 8 | Security context lookup failed.                     |
      +---+-----------------------------------------------------+
      | 9 | SID lookup failed.                                  |
      +---+-----------------------------------------------------+

  Pointer: 16 bits.
  
    Pointer to the record index associated with the error, if applicable.

  No message must ever be sent in response to an Error Response message.


7. Messaging Scenarios

  There are only three messaging scenarios:

  7.1 Successful Map Request/Response
  
  
    Peer X                                  Peer Y
    ------                                  ------ 
    
    Transmits a labeled datagram.   -->     .
    
                                            No current mapping for SID
                                            label available locally.
                                            Queue datagram.
                                                        
                                                        
    .                               <--     Transmit SCMP Map Request
                                            for SID.
      
    Lookup local security context
    for SID.
    
    Transmit SCMP Map Response      -->     .
    
                                            Lookup local SID for remote
                                            security context.  Cache
                                            SID mapping, relabel queued
                                            datagram with local SID and
                                            dequeue.
                                            

  7.2 Error Response to Map Request
  

    Peer X                                  Peer Y
    ------                                  ------ 
    
    Transmits a labeled datagram.   -->     .
    
                                            No current mapping for SID
                                            label available locally.
                                            Queue datagram.
                                                        
                                                        
    .                               <--     Transmit SCMP Map Request
                                            for SID.
      
    Lookup local security context
    for SID;  encounter system
    error due to solar flare.
    
    Transmit SCMP Error Response    -->     .
    

  7.3 Error Response to Map Response
  

    Peer X                                  Peer Y
    ------                                  ------ 
    
    Transmits a labeled datagram.   -->     .
    
                                            No current mapping for SID
                                            label available locally.
                                            Queue datagram.
                                                        
                                                        
    .                               <--     Transmit SCMP Map Request
                                            for SID.
      
    Lookup local security context
    for SID.
    
    Transmit SCMP Map Response      -->     .
    
                                            Lookup local SID for remote
                                            security context.  Cache
                                            lookup fails due to bug.
    
    .                               <--     Transmit SCMP Error Response.
    
    
8. Error Handling

  When encountering an error while processing a Map Request or Map Response
  message, a peer should normally report the error to the originating peer
  via an Error Response message.
  
  Exceptions to this are:
    o The received message does not pass header length validation.
    o The originating peer is not within the same security perimeter.
  
  It is assumed that the peer is authenticated and the payload protected
  from tampering per the traffic protection requirements mentioned in
  section (4).
  
  The purpose of an Error Response message is to allow the originating peer
  to perform local error handling and logging.
  
  No SCMP message of any kind must be transmitted in response to an Error
  Response message.

  
9. Security Considerations

  SCMP messages are required to be protected and authenticated, and SCMP
  peers are assumed to be trusted.  However, a flawed implementation
  could generate incorrect SCMP messages which adversely affect the
  security of a peer.
  
  Each SCMP message should be length validated at the datagram, SCMP
  payload and SCMP record levels.
  
  If the SCMP header cannot be reliably extracted, the message should
  be discarded without any further processing.
  
  IP addressees within payloads should be validated.  The source address
  in the Map Response payload should be verified against datagram source
  address.  Map Request messages will contain a destination address, and
  should be verified against local addresses or according to policy.

  
10. References

[1] Overview of SELinux Labeled Networking Support via CIPSO/FIPS-188
    IP Options, selopt-overview.txt.

[2] National Security Agency, Security Enhanced Linux,
    http://www.nsa.gov/selinux/

[3] Kent, S., and R. Atkinson, "Security Architecture for the Internet
    Protocol", RFC 2401, November 1998.


11. Author

  James Morris
  jmorris@intercode.com.au
  http://www.intercode.com.au/jmorris/
  

12. Acknowledgements

  Stephen Smalley reviewed the initial draft and suggested the inclusion
  of more specific error types for security context lookup failures.


13. Copyright

  This document is Copyright (c) 2002 James Morris and released under
  the terms of the GPL.


