RPCSEC_GSS Protocol Specification
updated by
- rfc-5403 — RPCSEC_GSS Version 2
Extracted elements (27)
GSS-API replay detection (replay_det_req_flag) and sequence enforcement (sequence_req_flag) are disabled at the GSS layer because RPCSEC_GSS implements its own sliding window that deliberately tolerates out-of-order delivery and dropped requests, which are inherent in RPC over unreliable transports and multi-threaded servers.
GSS-API tokens are placed in the NULLPROC call data body rather than in the RPC credential or verifier fields because RPC Version 2 restricts the credential and verifier to 400 octets each, while GSS tokens can exceed 800 octets. This 'overloading' of NULLPROC call data avoids the need to revise the RPC protocol.
RPCSEC_GSS has no built-in GSS-API mechanism or QOP negotiation; it is a mechanism-independent pass-through. Negotiation of {mechanism, QOP, service} must happen within the application protocol or via an out-of-band mechanism, because RPCSEC_GSS's role is only to convey whatever the application has already negotiated.
RPCSEC_GSS_CREDPROBLEM and RPCSEC_GSS_CTXPROBLEM may only be returned in responses to data exchange requests, not context creation requests. During context creation, an unsupported version or unrecognized flavor returns MSG_DENIED with AUTH_ERROR and AUTH_REJECTED_CRED.
Any application protocol referencing RPCSEC_GSS must specify a mandatory set of {mechanism, QOP, service} triples; an implementation cannot claim conformance unless it implements all required triples. RPCSEC_GSS itself does not mandate any specific mechanism.
Duplicate requests (sequence number already seen within the window) and requests with sequence numbers below the window must be silently discarded; the server does not send an error reply so that clients can recover by retrying with a new sequence number after timeout.
For integrity or privacy services, the server must reject the request (MSG_ACCEPTED, GARBAGE_ARGS) if the sequence number embedded in the request body differs from the sequence number in the credential.
For the first context creation request, gss_proc must be RPCSEC_GSS_INIT and the handle field must be NULL (zero-length opaque). For all subsequent creation requests, gss_proc must be RPCSEC_GSS_CONTINUE_INIT and handle must equal the value returned by the server. The seq_num and service fields are undefined and must be ignored during creation.
In the data exchange phase, the RPC request verifier flavor is RPCSEC_GSS and the body is the GSS_GetMIC() checksum of the entire RPC header up to and including the credential. The same QOP used for the header checksum must also be used for integrity or privacy protection of the data body.
The client must increment the sequence number for each retry of a request, even if the RPC transaction identifier (xid) is the same. The seq_num can start at any value below MAXSEQ and must be incremented by at least one for each successive request.
To destroy a context, the client sends a NULLPROC request with gss_proc=RPCSEC_GSS_DESTROY; the seq_num and header checksum in the verifier must both be valid for the server to accept the message. After exchange, both client and server must destroy the GSS-API context.
When a data request is denied with RPCSEC_GSS_CREDPROBLEM or RPCSEC_GSS_CTXPROBLEM, the client must refresh the context (destroy the old one, re-establish a new one) and retry the request. These two error codes must not appear in responses to context creation requests.
When calling GSS_Init_sec_context() during context creation, replay_det_req_flag and sequence_req_flag must be turned off because ONC RPC operates over unreliable transports, servers can be multi-threaded, and RPCSEC_GSS provides its own replay protection via sequence windows.
When gss_major equals GSS_S_COMPLETE in the context creation response, the response verifier flavor must be RPCSEC_GSS and the body must be GSS_GetMIC() of the seq_window value in network byte order using QOP=0 (default QOP). For all other gss_major values, a NULL verifier is used.
Appendix A defines numeric values for all GSS-API major status codes, since RFC 2078 (GSS-API v2) did not assign them. Key values: GSS_S_COMPLETE=0x00000000, GSS_S_CONTINUE_NEEDED=0x00000001. The 32-bit status code is partitioned into Calling Error (bits 31-24), Routine Error (bits 23-16), and Supplementary Info (bits 15-0) fields.
RPCSEC_GSS is assigned the security flavor value 6 in the auth_flavor enumeration: `RPCSEC_GSS = 6`.
The server maintains a sliding sequence number window of size seq_window. The server accepts requests with seq_num in the range [N - seq_window + 1, N] where N is the highest seen sequence number, plus any value above N that passes header checksum verification. Requests outside this lower bound are silently discarded.
Two new auth_stat values are defined: RPCSEC_GSS_CREDPROBLEM (13) returned when the server cannot find a valid context for the credential, and RPCSEC_GSS_CTXPROBLEM (14) returned when the sequence number exceeds MAXSEQ or security credentials expire.
An attacker monitoring traffic can inject requests with sequence numbers far above the current window. These pass the seq_num range check and force the server to perform header checksum verification, potentially enabling a CPU-exhaustion denial-of-service attack. Requests within or below the window are more cheaply discarded after optional early seq_num check.
Even with the rpc_gss_svc_privacy service, the RPC call header fields (program number, version number, procedure number) are transmitted in cleartext. Encrypting them would have required revising the RPC protocol; additionally, an attacker can typically determine program and version numbers by querying the rpcbind service on the destination host.
RPCSEC_GSS does not protect against message stealing (an attacker blocking or discarding messages undetected by the server). Implementing such protection would require the RPC service to maintain state, which is outside the scope of RPCSEC_GSS.
An RPCSEC_GSS session has three phases: (1) context creation, using RPCSEC_GSS_INIT then zero or more RPCSEC_GSS_CONTINUE_INIT exchanges until GSS_S_COMPLETE; (2) data exchange, with gss_proc=RPCSEC_GSS_DATA; (3) context destruction, using RPCSEC_GSS_DESTROY. Control messages use NULLPROC (procedure 0).
Integrity-protected request data is `struct rpc_gss_integ_data { opaque databody_integ<>; opaque checksum<>; }`. The databody_integ field is the XDR encoding of `struct rpc_gss_data_t { unsigned int seq_num; proc_req_arg_t arg; }`. The checksum is GSS_GetMIC() of the rpc_gss_data_t octet stream (not of databody_integ), using the same QOP as the header.
Privacy-protected request data is `struct rpc_gss_priv_data { opaque databody_priv<>; }`. The databody_priv field is the output of GSS_Wrap() on the XDR-encoded rpc_gss_data_t structure with conf_req_flag=TRUE and the same QOP as the header checksum.
The context creation request call data is `struct rpc_gss_init_arg { opaque gss_token<>; }` carrying the token from GSS_Init_sec_context(), placed after the verifier in the NULLPROC call body. All creation requests carry a NULL verifier (AUTH_NONE, zero-length).
The context creation success response encodes `struct rpc_gss_init_res { opaque handle<>; unsigned int gss_major; unsigned int gss_minor; unsigned int seq_window; opaque gss_token<>; }`. The seq_window field specifies the maximum number of concurrent outstanding requests the server accepts for this context.
The rpc_gss_cred_t XDR credential structure (version 1) contains: version (unsigned int), gss_proc (rpc_gss_proc_t: DATA=0, INIT=1, CONTINUE_INIT=2, DESTROY=3), seq_num (unsigned int), service (rpc_gss_service_t: none=1, integrity=2, privacy=3), and handle (variable-length opaque). MAXSEQ is defined as 0x80000000.