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/FIPS188 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.