API -> AcceptSecurityContext [ Library : digest.dll, Category : Security ] [C#, VB, VB.net]

AcceptSecurityContext

Library : digest.dll Category : Security

Api Example(s)
This is a link to different site 279815 - How To Validate User Credentials from Visual Basic by ...

API Description :

The AcceptSecurityContext function enables the server component of a transport application to establish a security context between the server and a remote client. The remote client uses the InitializeSecurityContext function to start the process of establishing a security context. The server can require one or more reply tokens from the remote client to complete establishing the security context. The Schannel implementation of AcceptSecurityContext returns the messages required by the selected protocol and a security token, which the server must pass to the client.

VB Declaration :

Show Multiline Public Private

Declare Sub AcceptSecurityContext Lib "digest" (ByRef phCredential As Long, ByRef phContext As Long, ByRef pInput As PSecBufferDesc, ByVaL fContextReq As Long, ByVaL TargetDataRep As Long, ByRef phNewContext As Long, ByRef pOutput As PSecBufferDesc, ByRef pfContextAttr As Long, ByRef ptsExpiry As PTimeStamp)

Parameters :

· phCredential 
[in] Handle to the server's credentials. The server calls the AcquireCredentialsHandle function with the INBOUND flag set to retrieve this handle. 
· phContext 
[in, out] Pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext, this pointer is NULL. On subsequent calls, phContext is the handle to the partially formed context that was returned in the phNewContext parameter by the first call. 
· pInput 
[in] Pointer to a SecBufferDesc structure generated by a client call to InitializeSecurityContext that contains the input buffer descriptor.
When using the Schannel security support provider (SSP), the first buffer must be of type SECBUFFER_TOKEN and contain the security token received from the client. The second buffer should be of type SECBUFFER_EMPTY.

The following table shows the buffer configuration for Digest HTTP. All buffers are of type SECBUFFER_TOKEN. Buffer # Contents 
0 Empty for the first call and the challenge response received from the client for the second call. 
1 Method. Characters are wireline format from the request line. 
2 Reserved. 
3 HEntity. Hexadecimal representation of H(entity-body). US ASCII single-byte characters. 
4 Realm. Realm string for the challenge. Unicode string that must be representable in US ASCII. 
SASL requires only buffer zero.

· fContextReq 
[in] Bit flags that specify the attributes required by the server to establish the context. Bit flags can be combined using bitwise-OR operations.Value Meaning 
ASC_REQ_INTEGRITY Sign messages and verify signatures.
Valid with the Digest SSP.
 
ASC_REQ_CONFIDENTIALITY Encrypt and decrypt messages. 
Valid with the Digest SSP for SASL only.

Valid with Schannel SSP.
 
ASC_REQ_ALLOCATE_MEMORY Digest and Schannel will allocate output buffers for you. When you have finished using the output buffers, free them by calling the FreeContextBuffer function.
Valid with the Digest SSP and the Schannel SSP.
 
ASC_REQ_REPLAY_DETECT Detect replayed packets.
Valid with the Digest SSP.

Valid with Schannel SSP.
 
ASC_REQ_SEQUENCE_DETECT Detect messages received out of sequence.
Valid with Schannel SSP.
 
ASC_REQ_STREAM Support a stream-oriented connection. Schannel will set this flag automatically if you do not.
Valid with Schannel SSP.
 
ASC_REQ_EXTENDED_ERROR When errors occur, the remote party will be notified.
Valid with Schannel SSP.
 
ASC_REQ_CONNECTION The security context will not handle formatting messages.
Valid with Schannel SSP.
 
ASC_REQ_MUTUAL_AUTH The client is required to supply a certificate to be used for client authentication.
Valid with Schannel SSP.
 
ASC_REQ_DELEGATE The server is allowed to impersonate the client. Valid for Kerberos. Ignore this flag for constrained delegation. 
ASC_REQ_HTTP (0x10000000) Use Digest for HTTP. Omit this flag to use Digest as an SASL mechanism. 


For possible attribute flags and their meanings, see Context Requirements. Flags used for this parameter are prefixed with ASC_REQ, such as ASC_REQ_DELEGATE.

The requested attributes may not be supported by the client. For more information, see the pfContextAttr parameter.


· TargetDataRep 
[in] Indicates the data representation, such as byte ordering, on the target. Can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.
Not used with Schannel or Digest SSPs. Specify zero when used with either of these packages.

· phNewContext 
[in, out] Pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext, this pointer receives the new context handle. On subsequent calls, phNewContext can be the same as the handle specified in the phContext parameter. 
· pOutput 
[in, out] Pointer to a SecBufferDesc structure that contains the output buffer descriptor. This buffer is sent to the client for input into additional calls to InitializeSecurityContext. An output buffer may be generated even if the function returns SEC_E_OK. Any buffer generated must be sent back to the client application.
When using Schannel, on output, this buffer receives a token for the security context. The token must be sent to the client. The function can also return a buffer of type SECBUFFER_EXTRA.

· pfContextAttr 
[out] Pointer to a variable that receives a set of bit flags that indicate the attributes of the established context. For a description of the various attributes, see Context Requirements. Flags used for this parameter are prefixed with ASC_RET, for example, ASC_RET_DELEGATE.
Do not check for security-related attributes until the final function call returns successfully. Attribute flags not related to security, such as the ASC_RET_ALLOCATED_MEMORY flag, can be checked before the final return.

· ptsTimeStamp 
[out] Pointer to a TimeStamp structure that receives the expiration time of the context. It is recommended that the security package always return this value in local time.
There is no expiration time for Digest security contexts or credentials and when using the Digest SSP; this parameter is set to a constant maximum time.

This is optional when using the Schannel SSP. When the remote party has supplied a certificate to be used for authentication, this parameter receives the expiration time for that certificate. If no certificate was supplied, a maximum time value is returned.

Note  Until the last call of the authentication process, the expiration time for the context can be incorrect because more information will be provided during later stages of the negotiation dialog. Therefore, ptsTimeStamp must be NULL until the last call to the function.

Windows 2000, Windows NT, Windows Me/98/95:  This parameter is not used. Set this value to NULL.

Return :

This function returns one of the following values.Return code/value Description 
SEC_E_OK (0x00000000L) The function succeeded. The security context received from the client was accepted. If an output token was generated by the function, it must be sent to the client process. 
SEC_I_CONTINUE_NEEDED (0x00090312L) The function succeeded. The server must send the output token to the client and wait for a returned token. The returned token should be passed in pInput for another call to AcceptSecurityContext. 
SEC_I_COMPLETE_NEEDED (0x00090313L) The function succeeded. The server must finish building the message from the client, then call the CompleteAuthToken function. 
SEC_I_COMPLETE_AND_CONTINUE (0x00090314L) The function succeeded. The server must call CompleteAuthToken and pass the output token to the client. The server then waits for a return token from the client and then makes another call to AcceptSecurityContext.  
SEC_E_INVALID_TOKEN (0x80090308L) The function failed. The token passed to the function is invalid. 
SEC_E_INVALID_HANDLE (0x80100003L) The function failed. The handle passed to the function is invalid. 
SEC_E_LOGON_DENIED (0x8009030CL) The logon failed. 
SEC_E_INTERNAL_ERROR (0x80090304L) The function failed. An error occurred that did not map to an SSPI error code. 
SEC_E_NO_AUTHENTICATING_AUTHORITY (0x80090311L) The function failed. No authority could be contacted for authentication. This could be due to the domain name of the authenticating party being wrong, the domain being unreachable, or to a trust relationship failure. 
SEC_E_NO_CREDENTIALS (0x8009030EL) The function failed. The credentials handle specified in the phCredential parameter is invalid. This value can be returned when using the Digest or Schannel SSP. 
SEC_E_SECURITY_QOS_FAILED (0x80090332L) The function failed. An invalid context attribute flag was specified in the fContextReq parameter. This value can be returned when using the Digest SSP. 
STATUS_LOGON_FAILURE (0xC000006DL) The function failed. AcceptSecurityContext was called after the specified context was established. This value can be returned when using the Digest SSP. For more information, see Remarks. 
SEC_E_INCOMPLETE_MESSAGE (0x80090318L) The function succeeded. The data in the input buffer is incomplete. The application must read additional data from the client and call AcceptSecurityContext again. This value can be returned when using the Schannel SSP. 
SEC_E_UNSUPPORTED_FUNCTION (0x80090302L) The function failed. An invalid context attribute flag (ASC_REQ_DELEGATE or ASC_REQ_PROMPT_FOR_CREDS) was specified in the fContextReq parameter. This value can be returned when using the Schannel SSP. 
SEC_E_INSUFFICIENT_MEMORY (0x80090300L) Not enough memory is available to complete the request.

OS Requirement :

Dotnet Replacement :