3.2.4.3 S_InitSecCtx (Opnum 2)

  • Article

This method is a callback method called by the server during a client call to S_DSValidateServer. These two methods are used to tunnel a GSS (as specified in [RFC2743]) security negotiation to provide mutual authentication between the client and server.

 [callback] HRESULT S_InitSecCtx(
   [in] unsigned long dwContext,
   [in, size_is(dwServerBuffSize)] 
     unsigned char* pServerbuff,
   [in, range(0,524288)] unsigned long dwServerBuffSize,
   [in, range(0,524288)] unsigned long dwClientBuffMaxSize,
   [out, size_is(dwClientBuffMaxSize), length_is(*pdwClientBuffSize)] 
     unsigned char* pClientBuff,
   [out] unsigned long* pdwClientBuffSize
 );

dwContext:  MUST be set by the caller to the correlation value supplied by the client in the dwContext parameter in the corresponding call to S_DSValidateServer. This parameter provides a way for the receiver to correlate the callback with the receiver's in-progress call to S_DSValidateServer.

pServerbuff:  MUST be set by the caller to point to a buffer that contains the output_token from the GSS_Accept_sec_context, as specified in [RFC2743].

dwServerBuffSize:  MUST be set by the caller to the length, in bytes, of the output_token within pServerBuff.

dwClientBuffMaxSize:  MUST be set by the caller to the size, in bytes, of the buffer to be returned in pClientBuff.

pClientBuff:  MUST be set by the caller to point to a buffer to hold the returned token. MUST be set by the receiver to the output_token from a call to GSS_Init_sec_context. The buffer length MUST NOT exceed the value specified by dwClientBuffMaxSize. If the negotiated token is larger than the supplied buffer, the server MUST return MQ_ERROR_USER_BUFFER_TOO_SMALL (0xC00E0028).

pdwClientBuffSize:  MUST be set by the receiver to the actual size, in bytes, of the token in pClientBuff.

Return Values:  If the method succeeds, and the negotiation is complete, the return value is 0. If the method succeeds, and the negotiation is not complete, the return value is SEC_I_CONTINUE_NEEDED (0x00090312). If the method fails, the return value is an implementation-specific error code.

ERROR_SUCCESS (0x00000000)

SEC_I_CONTINUE_NEEDED (0x00090312)

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

The caller MUST supply an input_token in pServerBuff computed through a call to GSS_Accept_sec_context. The receiver MUST process this input_token through a call to GSS_Init_sec_context, generating an output_token that MUST be returned in pServerBuff.

If GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED, this is a signal that the negotiation is not complete. The receiver MUST return SEC_I_CONTINUE_NEEDED (0x00090312).

If GSS_Init_sec_context returns GSS_S_COMPLETE, the negotiation is complete. The receiver MUST save the output context handle in the GSS security context state associated with the dwContext parameter. The receiver MUST return SEC_E_OK (0x00000000).