3.3.1.5.2.1 Building a Security Context

  • Article

To make a secure call, a security context needs to be created before it can be used. The process of creation involves exchanging one or more messages between the client and server implementations of a security provider. This process is also called building a security context.

During the process of building a security context, a security provider can optionally exchange messages with an entity other than the client or server (for example, a KDC).

The scope of a built security context is the connection. If a client wants to use a security context on a different connection, it MUST totally rebuild it for that different connection.

To build a security context, an RPC client and an RPC server exchange a series of bind/bind_ack or alter_context/alter_context_resp PDUs with authentication information. The process MUST start on the client, as follows:

  • If the client has already sent a bind PDU on the connection it wants to build the security context on, it MUST start the sequence of building a security context with an alter_context PDU.

  • If the client has not already sent a bind PDU on that connection, it MUST start the sequence of building a security context with a bind PDU.

The process continues on the server as follows:

  • If the server receives a bind PDU, it MUST respond with a bind_ack or bind_nak PDU.

  • If a server receives an alter_context PDU, it MUST respond with an alter_context_resp PDU or, in the case of error, with a fault PDU.

In case of catastrophic errors (such as an out of memory condition or buffer overrun), a server MAY send a fault PDU or just close the connection. For information on client and server state machines, see sections 3.3.2 and 3.3.3.

Once a client decides on the type of PDU, it MUST start the sequence by requesting the security provider for an authentication token using an implementation-specific equivalent of the abstract GSS_Init_sec_context call, as specified in [RFC2743]. See [MS-APDS] section 3.1.5 for NTLM details and see [RFC4121] and [MS-KILE] section 3.2.5.2 for Kerberos details. This PDU MUST be sent to the server with authentication information added, as specified in section 2.2.2.11.

When authentication information is associated with a connection as specified in section 2.2.2.11 and auth_length is nonzero as specified in [C706] section 13.2.6, the Security Context contains a token that represents the client identity populated by the security provider. See [MS-APDS] section 3.1.5 "Processing Events and Sequencing Rules" and [MS-KILE] section 3.4.5.3 "Processing Authorization Data" for details of population of the token. See [MS-DTYP] section 2.5.2 "Token/Authorization Context" for details of the members of tokens.

If no authentication information is obtainable as specified in section 2.2.2.11 and the transport protocol is NCACN_NP, the security context is obtained as described in [MS-CIFS] section 3.5.4.3 supplying the Connection NamedPipe ADM element as a parameter.

The client MUST choose a value for the auth_context_id of the sec_trailer structure such that it is unique within the scope of the given connection. Each message with an authentication token sent to the other party is also called a security leg. Thus, the first message from the client to the server is also called the first leg of the security context creation. The server MUST retrieve the authentication token and hand it off to the security provider indicated by the auth_type field.

The interaction between these extensions and the security provider on the server MUST happen through an implementation-specific equivalent of the abstract GSS_Accept_sec_context call, as specified in [RFC2743]. Upon receiving and processing an authentication token at any leg of the authentication on either the client or server, the security provider MUST indicate to RPC runtime one of three abstract results from the processing: an error, a success, or a request for further security legs, as specified in [RFC2743]:

  • If the security provider indicates an error, the RPC runtime MUST take recovery action depending on whether this is the client or server.

    • If this is the client, the RPC runtime discards the security context and MUST NOT send any further PDUs on that connection. It SHOULD close the connection unless it is expecting responses on a multiplexed connection, as specified in section 3.3.1.5.8, in which case it SHOULD set the Activity's Discard flag to TRUE. If it does not wait for all responses on a multiplexed connection, it MUST provide indication in an implementation-specific way to upper layers that the outstanding calls have failed.

    • If the security provider returns an error on the server, the server MUST respond with a bind_nak or a fault PDU, depending on the PDU that the client sent, as specified earlier. The server SHOULD also discard the security context in this case.

  • If the security provider returns a success from processing the authentication token, the security context is successfully created. If the security provider returns a success on the client, the client is ready to use this security context. If the security provider on the server returns a success, the server MUST still respond with a bind_ack or alter_context_resp PDU, as specified earlier. In this case, it SHOULD return an empty (zero-length) authentication token to the client.

  • If the security provider indicates to the RPC runtime a request for further security legs, it MUST always produce another authentication token along with the request for further security legs. In this case, the RPC runtime MUST send another leg of the security context creation by using that authentication token. If this happens on the client, the client MUST send an alter_context PDU. The p_context_elem structure of the alter_context PDU SHOULD be the same as the content of the PDU sent in the previous leg from the client. If this happens on the server, it MUST respond with a bind_ack or an alter_context_resp PDU, except when a security provider has an odd number of legs as specified in the following section, using the authentication token produced by the security provider.

If a client has implemented a Table of Security Provider Info, then it has the knowledge of how many legs different security providers use . If the client determines during lookup in this table that a given security provider has an odd number of legs, the client SHOULD use an rpc_auth_3 PDU instead of an alter_context PDU for the last leg. The client MUST NOT use an rpc_auth_3 PDU unless it is certain that the current leg is the last leg of exchange. The server MUST NOT respond to an rpc_auth_3 PDU. If the processing of the authentication token from an rpc_auth_3 PDU results in an error, the RPC runtime on the server SHOULD return a fault PDU on the first request that uses this security context with the status field set to the security context handle Error Value.

If a client is not sure how many legs a given security provider uses, it MUST assume that the number of legs is even.<98>

Once negotiated, the client and server add the resultant security context handle to the connection's Table of Security Context Handles.