3.2.1.4.1 Building and Using 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 Key Distribution Center (KDC)), but this exchange is not addressed in this document. The scope of a built security context is the activity. If a client wants to use a security context on a different activity, it MUST totally rebuild it for that different activity.

Upon receiving and processing an authentication token at any point in 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 takes recovery action that is dependent on the location of the error.

The process of building a security context MUST start on the client. The client begins the process by using the server binding handle's AuthIdentity to create an authentication token using the server binding handle's specified security provider identifier by invoking an implementation-specific equivalent of the abstract GSS_Init_sec_context call, as specified in [RFC2743]. The client MUST choose a value for the key_vers_num field of the sec_trailer_cl structure such that it is unique within the scope of the given activity. The client then MUST use the token to sign or seal one or more request PDUs and then sends them to the server. If any of these steps encounters a failure, the client RPC runtime MUST set the activity's Discard flag to TRUE and discard the activity unless it is expecting responses to other calls belonging to the activity. For details on multiple calls on the same activity, see section 3.2.1.5.2

When the server receives a PDU containing a nonzero auth_proto field, it checks the key_vers_num field of the PDUs sec_trailer_cl structure. If the server does not already have a security context in the Table of Security Contexts matching the key_vers_num, it MUST do the following:

  • Locate a Security Provider from the Table of Security Providers using the value in the auth_proto field.

  • Request that it create a new security context.

  • Create a token through an implementation-specific equivalent of the abstract GSS_Accept_sec_context call, as specified in [RFC2743].

The server MUST send the token to the client by creating a binding handle to the client and calling conv_who_are_you_auth with the token in the in_data parameter. If the token is large enough to require calls to conv_who_are_you_auth_more, the server MUST preserve the token in the server's security buffer in the activity entry in the Table of Activity IDs until it has sent the entire token to the client. If the security provider returns success from processing the authentication token, the security context is successfully created. If any of these steps encounters an error, the server SHOULD send a fault or reject PDU, as appropriate, and discard the security context.

The client MUST provide the token to its security provider by using an implementation-specific equivalent of the abstract GSS_Init_sec_context call, as specified in [RFC2743], and MUST send the response token to the server in the out_data parameter of the conv_who_are_you_auth. If the response token is large enough to require calls to conv_who_are_you_auth_more, the client MUST preserve the token in the client activity's security buffer, until it has returned all of the token to the server. If the security provider returns success from processing the authentication token, the security context is successfully created. If any of these steps encounters an error, the client SHOULD send a fault or reject PDU, as appropriate, and discard the security context.

If the security provider indicates a request for further security legs, the server SHOULD send a nocall PDU to the client and discard the security context.

For information on client and server state machines, see sections 3.2.2.1 and 3.2.3.1.

Once negotiated, a security context SHOULD be maintained by both client and server implementations for the lifetime of the activity it is negotiated on, unless the security provider indicates that the context has expired by returning the SEC_E_CONTEXT_EXPIRED error when the RPC runtime attempts to use the security context.

If security contexts are maintained, then the client SHOULD store the resultant security context handle in the client activities security context handle property. The client SHOULD store the client credential handle used to create the security context handle in the client activity's client credential handle property. The server SHOULD store the resultant security context handle in the appropriate Table of Activity IDs Table of Security Contexts.

If the client received an error using the security context, it MUST attempt to build another security context as described previously in this section.

If the server receives an error using the security context, the packet that it is currently being processed is discarded.