3.1.4.2 S_DSValidateServer (Opnum 22)

This method performs mutual authentication between the client and server, and establishes a security context, as specified in [RFC2743]. The server uses the security context to construct a digital signature in subsequent method calls of this protocol, and the client uses the security context to validate the digital signature. The digital signature is used in methods that return data to the client. It allows the client to authenticate the source of the data and ensures that it has not been tampered with en route from the server to the client.

When the client has no further use of the RPC context handle returned from this method, it releases the handle through a subsequent call to S_DSCloseServerHandle (section 3.1.4.3).

 HRESULT S_DSValidateServer(
   [in] handle_t hBind,
   [in] const GUID* pguidEnterpriseId,
   [in] BOOL fSetupMode,
   [in] unsigned long dwContext,
   [in, range(0,524288)] unsigned long dwClientBuffMaxSize,
   [in, size_is(dwClientBuffMaxSize), length_is(dwClientBuffSize)] 
     unsigned char* pClientBuff,
   [in, range(0,524288)] unsigned long dwClientBuffSize,
   [out] PPCONTEXT_HANDLE_SERVER_AUTH_TYPE pphServerAuth
 );

hBind:  MUST specify an RPC binding handle, as specified in [MS-RPCE] section 2.

pguidEnterpriseId:  MUST be set by the client to a pointer to the GUID of the enterprise that owns the server. The server SHOULD ignore it.<17>

fSetupMode:  Boolean value that defines the setup mode. Clients SHOULD set this value to FALSE (0x00000000). The server SHOULD ignore it.<18>

dwContext:  MUST be set by the client to a value that the client can use to correlate callbacks with the initial call to S_DSValidateServer. The server MUST supply this value in the dwContext parameter in the related calls of the S_InitSecCtx (section 3.2.4.3) callback method.

dwClientBuffMaxSize:  MUST be set by the client to the size of the buffer pointed to by the pClientBuff parameter.

pClientBuff: A pointer that MUST be set by the client to point to a buffer that contains the output_token from an initial call to GSS_Init_sec_context, as specified in [RFC2743] section 2.2.1.

dwClientBuffSize:  MUST be set by the client to the size in bytes of the output_token within the client buffer pointed at by the pClientBuff parameter.

pphServerAuth:  MUST be set by the server to a PCONTEXT_HANDLE_SERVER_AUTH_TYPE (section 2.2.5) RPC context handle.

Return Values:  If the method succeeds, the return value is 0. If the method fails, the return value is an implementation-specific error code.

MQ_OK (0x00000000)

MQ_ERROR_DS_ERROR (0xC00E0043)

MQDS_E_CANT_INIT_SERVER_AUTH (0xC00E052B)

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol as specified in [MS-RPCE].

If the dwClientBuffSize parameter is zero, the server MUST initialize an empty security context in the security context table associated with the pphServerAuth parameter and MUST NOT invoke client callback methods. In addition, all signature parameters in other methods in this protocol that return server signatures MUST be set to all zeros.

If the dwClientBuffSize parameter is nonzero, the server MUST construct a valid non-empty security context in the security context table associated with the pphServerAuth parameter.

The client MUST supply an input_token in the pClientBuff parameter, acquired through an initial call to GSS_Init_sec_context, as specified in [RFC2743] section 2.2.1. The server MUST perform the following processing.

  1. Let inputToken point to an input_token initialized to the pClientBuff parameter.

  2. Call GSS_Accept_sec_context, as specified in [RFC2743] section 2.2.2, with the input_token contained in inputToken and a NULL input_context_handle.

  3. If GSS_Accept_sec_context returns GSS_S_COMPLETE, the negotiation is complete. The server MUST allocate a PCONTEXT_HANDLE_SERVER_AUTH_TYPE RPC context handle and MUST allocate a security context entry in the security table keyed by the context handle. The server MUST associate the GSS security context (output_context_handle from the GSSAPI call) with the security context entry. The server MUST return the RPC context handle in the pphServerAuth parameter and return MQ_OK.

  4. If GSS_Accept_sec_context returns GSS_S_CONTINUE_NEEDED, the server MUST issue a callback to the client through the S_InitSecCtx (section 3.2.4.3) method with the dwContext parameter set to the value supplied by the client in the dwContext parameter and the pServerBuff parameter set to the output_token returned from GSS_Accept_sec_context. When the callback to S_InitSecCtx returns, the server MUST set inputToken to the pClientBuff parameter returned by S_InitSecCtx and MUST continue at step 2.

  5. If GSS_Accept_sec_context returns any other value, the server MUST take no further action and return a failure HRESULT.

The GSS security context is used by the server in subsequent calls to GSSWrap, as specified in [RFC2743] section 2.3.3.

On successful return, the client MUST retrieve the GSS security context associated with the dwContext parameter and MUST associate it with the PCONTEXT_HANDLE_SERVER_AUTH_TYPE RPC context handle returned in the pphServerAuth parameter. The GSS security context will be used by the client in subsequent calls to GSSUnwrap, as specified in [RFC2743] section 2.3.4.