The COPS (Common Open Policy Service) Protocol
updated by
- rfc-4261 — Common Open Policy Service (COPS) Over Transport Layer Security (TLS)
Extracted elements (30)
COPS uses a single persistent TCP connection between PEP and PDP, eliminating the need for additional reliability mechanisms. The protocol is stateful so that request/decision pairs are installed and remembered at the PDP until explicitly deleted, allowing the PDP to issue unsolicited decisions at any time for currently installed states.
The protocol is designed to be extensible via self-identifying objects (C-Num/C-Type) so that diverse client-specific information can be supported without modifying the base COPS protocol. New client-types are expected to have corresponding usage documents specifying their interaction with the protocol.
To avoid deadlock when a PEP issues a REQ that never receives a DEC, the PEP can timeout and MUST then delete the timed-out handle before retrying with a new handle. The PDP SHOULD NOT receive more than one outstanding solicited REQ per handle before responding.
When SNMP is supported by the PEP, the ifindex values in the IN-Int and OUT-Int objects MUST correspond to the same integer values used for the interface in the SNMP MIB-II interface index table, enabling consistent interface identification across management protocols.
A client handle MUST be explicitly deleted by the PEP before it can be reused for a new request state. Handles referring to different request states MUST be unique within the context of a particular TCP connection and client-type.
A PEP that caches state from a disconnected PDP MUST communicate this to any PDP it reconnects to by including the LastPDPAddr object (C-Num=14) in the Client-Open message. States deleted during the disconnection MUST be explicitly deleted after reconnection.
All COPS implementations MUST support the COPS Integrity object and its mechanisms, including HMAC-MD5-96 as the mandatory minimum cryptographic algorithm (HMAC applied to MD5, truncated to 96 bits). The Keyed Message Digest field MUST be 96 bits when HMAC-MD5-96 is used.
For every DEC message containing a configuration context, the PEP MUST generate a corresponding RPT message with the Solicited Message flag set. RPT messages solicited by decisions for a given Client Handle MUST be sent in the same order as their corresponding DEC messages were received, and there MUST never be more than one solicited RPT per Decision.
If security is required and a COPS message is received without a valid Integrity object, the receiver MUST send a Client-Close message for Client-Type=0 with the appropriate error code. Once integrity is negotiated, ALL subsequent COPS messages must include the negotiated Integrity object with the correct sequence number.
Key maintenance MUST at minimum support manual configuration of keys and their parameters locally. Keys MUST be configurable with overlapping lifetimes to allow smooth transitions; senders should switch to the longer-lived key at the midpoint of the overlap period.
Malformed Decision messages MUST trigger a DRQ from the PEP with the Bad Message Format reason code, and associated state SHOULD be removed or re-requested. If a Decision contained an unknown COPS Decision Object, the PEP MUST delete its request state using the Unknown COPS Object reason code.
The PDP MUST always issue decisions for requests on a particular handle in the order they arrive, and all requests MUST have a corresponding decision. The first decision for a new or updated request MUST have the Solicited Message flag set in the COPS header.
The PEP MUST generate a Keep-Alive message randomly between 1/4 and 3/4 of the minimum KA Timer interval across all received CAT messages. Upon receiving a KA, the PDP MUST echo a KA back to the PEP. The client-type in KA messages MUST always be set to 0.
The PEP MUST keep trying all configured PDPs until a connection is established. If a PEP is connected to a backup PDP and the primary PDP becomes available, the backup PDP is responsible for redirecting the PEP to the primary via a Client-Close message containing a PDPRedirAddr object.
When the PDP issues an SSQ message referencing a specific handle that the PEP does not recognize, the PEP MUST immediately send a DRQ for that handle. If no handle is specified, the PEP MUST synchronize all active state and then MUST issue a Synchronize State Complete (SSC) message when finished.
COPS defines 10 message Op Codes: REQ (1), DEC (2), RPT (3), DRQ (4), SSQ (5), OPN (6), CAT (7), CC (8), KA (9), and SSC (10). The Client-type field (16 bits) identifies the policy client; values 0x8000–0xFFFF are enterprise-specific.
The Context Object (C-Num=2, C-Type=1) specifies the event type that triggered a request via a 16-bit R-Type flag field (0x01=Incoming-Message/Admission Control, 0x02=Resource-Allocation, 0x04=Outgoing-Message, 0x08=Configuration) and a 16-bit client-specific M-Type field.
The COPS common header is a fixed 8-octet structure containing a 4-bit Version field (current version 1), 4-bit Flags field (including the Solicited Message Flag bit 0x1), 8-bit Op Code (1–10), 16-bit Client-type, and 32-bit Message Length. Messages MUST be aligned on 4-octet intervals.
The Decision Object (C-Num=6) is sent by the PDP and includes mandatory Decision Flags (C-Type=1) with a 16-bit Command-Code (0=NULL, 1=Install, 2=Remove) and a 16-bit Flags field (0x01=Trigger Error). Optional subtypes include Stateless Data (C-Type=2), Replacement Data (C-Type=3), Client Specific Decision Data (C-Type=4), and Named Decision Data (C-Type=5).
The Handle Object (C-Num=1, C-Type=1) is a variable-length opaque value chosen by the PEP to uniquely identify an installed request state per client-type per TCP connection. The PDP performs only byte-wise comparison; it is always initiated and deleted by the PEP.
The KA Timer Object (C-Num=10, C-Type=1) encodes the maximum interval between COPS messages as an unsigned 16-bit integer in seconds (range 1–65535; 0 implies infinity). The Accounting Timer Object (C-Num=15, C-Type=1) uses the same encoding to set the minimum interval between accounting reports.
The PEPID Object (C-Num=11, C-Type=1) is a NULL-terminated ASCII string zero-padded to a 32-bit boundary that uniquely identifies the PEP within the policy domain in a manner persistent across reboots (e.g., static IP address or DNS name). It is required in Client-Open messages.
Client-type values are managed by IANA: 0x0001–0x3FFF require Specification Required registration and a COPS extension document; 0x4000–0x7FFF are Private Use (not tracked); 0x8000–0xFFFF are First Come First Served (tracked for uniqueness). New C-Num/C-Type values and changes to R-Types, Reason-Codes, Error-Codes, and Decision Flags require IETF Consensus.
COPS integrity via HMAC provides authentication, message integrity, and replay prevention using sequence numbers. Initial sequence numbers SHOULD be chosen to be monotonically increasing and never repeat for a particular key. It is good practice to use localized keys per PEP so that a stolen PEP does not compromise the entire administrative domain.
COPS security MAY alternatively be provided at the network layer via IPsec (AH SHOULD be used for validation; ESP MAY add secrecy) or at the transport layer via TLS for connection-level validation and privacy. These mechanisms are complements to or replacements for the COPS Integrity object.
COPS security is negotiated once per connection using Client-Type=0 OPN/CAT exchange before any other client-type is opened. The PEP sends OPN with Client-Type=0 containing PEPID and an Integrity object; the PDP responds with CAT containing its own Integrity object, establishing bidirectional sequence numbers. Failure results in Client-Close with an error code (Authentication Required, Unknown COPS Object, or Authentication Failure).
PEP initialization proceeds: (1) TCP connection established, (2) optional security negotiation via Client-Type=0 OPN/CAT, (3) PEP sends OPN per supported client-type, (4) PDP responds with CAT (accepted) or CC (rejected, possibly with redirect). After CAT, PEP may begin issuing REQ messages.
All COPS objects share a common 4-octet header: a 16-bit Length (in octets, including the header), an 8-bit C-Num (class identifier), and an 8-bit C-Type (subtype). Objects whose length does not fall on a 32-bit boundary MUST be padded to the next 32-bit boundary before transmission.
The In-Interface (C-Num=3) and Out-Interface (C-Num=4) objects each carry an IPv4 address (C-Type=1, 4 octets) or IPv6 address (C-Type=2, 16 octets) followed by a 32-bit ifindex. When SNMP is supported by the PEP, the ifindex MUST correspond to the MIB-II interface index.
The Message Integrity Object (C-Num=16, C-Type=1) contains a 32-bit Key ID, a 32-bit Sequence Number, and a variable-length Keyed Message Digest. The digest is computed over the entire COPS message including the Integrity object header, Key ID, and Sequence Number, but excluding the digest field itself.