Export (0) Print
Expand All
0 out of 1 rated this helpful - Rate this topic

DecryptMessage (General) function

The DecryptMessage (General) function decrypts a message. Some packages do not encrypt and decrypt messages but rather perform and check an integrity hash.

The Digest security support provider (SSP) provides encryption and decryption confidentiality for messages exchanged between client and server as a SASL mechanism only.

This function is also used with the Schannel SSP to signal a request from a message sender for a renegotiation (redo) of the connection attributes or for a shutdown of the connection.

Note  EncryptMessage (General) and DecryptMessage (General) can be called at the same time from two different threads in a single Security Support Provider Interface (SSPI) context if one thread is encrypting and the other is decrypting. If more than one thread is encrypting, or more than one thread is decrypting, each thread should obtain a unique context.

For information about using this function with a specific SSP, see the following topics.

TopicDescription
DecryptMessage (Digest) Decrypts a message by using Digest.
DecryptMessage (Kerberos) Decrypts a message by using Kerberos.
DecryptMessage (Negotiate) Decrypts a message by using Negotiate.
DecryptMessage (NTLM) Decrypts a message by using NTLM.
DecryptMessage (Schannel) Decrypts a message by using Schannel.

 

Syntax


SECURITY_STATUS SEC_Entry DecryptMessage(
  _In_     PCtxtHandle phContext,
  _Inout_  PSecBufferDesc pMessage,
  _In_     ULONG MessageSeqNo,
  _Out_    PULONG pfQOP
);

Parameters

phContext [in]

A handle to the security context to be used to decrypt the message.

pMessage [in, out]

A pointer to a SecBufferDesc structure. On input, the structure references one or more SecBuffer structures. One of these may be of type SECBUFFER_DATA. That buffer contains the encrypted message. The encrypted message is decrypted in place, overwriting the original contents of its buffer.

When using the Digest SSP, on input, the structure references one or more SecBuffer structures. One of these must be of type SECBUFFER_DATA or SECBUFFER_STREAM, and it must contain the encrypted message.

When using the Schannel SSP with contexts that are not connection oriented, on input, the structure must contain four SecBuffer structures. Exactly one buffer must be of type SECBUFFER_DATA and contain an encrypted message, which is decrypted in place. The remaining buffers are used for output and must be of type SECBUFFER_EMPTY. For connection-oriented contexts, a SECBUFFER_DATA type buffer must be supplied, as noted for nonconnection-oriented contexts. Additionally, a second SECBUFFER_TOKEN type buffer that contains a security token must also be supplied.

MessageSeqNo [in]

The sequence number expected by the transport application, if any. If the transport application does not maintain sequence numbers, this parameter must be set to zero.

When using the Digest SSP, this parameter must be set to zero. The Digest SSP manages sequence numbering internally.

When using the Schannel SSP, this parameter must be set to zero. The Schannel SSP does not use sequence numbers.

pfQOP [out]

A pointer to a variable of type ULONG that receives package-specific flags that indicate the quality of protection.

When using the Schannel SSP, this parameter is not used and should be set to NULL.

This parameter can be one of the following flags.

ValueMeaning
SECQOP_WRAP_NO_ENCRYPT

The message was not encrypted, but a header or trailer was produced.

Note  KERB_WRAP_NO_ENCRYPT has the same value and the same meaning.

SIGN_ONLY

When using the Digest SSP, use this flag when the security context is set to verify the signature only. For more information, see Quality of Protection.

 

Return value

If the function verifies that the message was received in the correct sequence, the function returns SEC_E_OK.

If the function fails to decrypt the message, it returns one of the following error codes.

Return codeDescription
SEC_E_BUFFER_TOO_SMALL

The message buffer is too small. Used with the Digest SSP.

SEC_E_CRYPTO_SYSTEM_INVALID

The cipher chosen for the security context is not supported. Used with the Digest SSP.

SEC_E_INCOMPLETE_MESSAGE

The data in the input buffer is incomplete. The application needs to read more data from the server and call DecryptMessage (General) again.

SEC_E_INVALID_HANDLE

A context handle that is not valid was specified in the phContext parameter. Used with the Digest and Schannel SSPs.

SEC_E_INVALID_TOKEN

The buffers are of the wrong type or no buffer of type SECBUFFER_DATA was found. Used with the Schannel SSP.

SEC_E_MESSAGE_ALTERED

The message has been altered. Used with the Digest and Schannel SSPs.

SEC_E_OUT_OF_SEQUENCE

The message was not received in the correct sequence.

SEC_E_QOP_NOT_SUPPORTED

Neither confidentiality nor integrity are supported by the security context. Used with the Digest SSP.

SEC_I_CONTEXT_EXPIRED

The message sender has finished using the connection and has initiated a shutdown. For information about initiating or recognizing a shutdown, see Shutting Down an Schannel Connection. Used with the Schannel SSP.

SEC_I_RENEGOTIATE

The remote party requires a new handshake sequence or the application has just initiated a shutdown. Return to the negotiation loop and call AcceptSecurityContext (General) or InitializeSecurityContext (General), passing empty input buffers.

If the function returns a buffer of type SEC_BUFFER_EXTRA, this should be passed to the AcceptSecurityContext (General) function as an input buffer.

Used with the Schannel SSP.

Renegotiation is not supported for Schannel kernel mode. The caller should either ignore this return value or shut down the connection. If the value is ignored, either the client or the server might shut down the connection as a result.

 

Remarks

When you use the Schannel SSP, the DecryptMessage (General) function returns SEC_I_CONTEXT_EXPIRED when the message sender has shut down the connection. For information about initiating or recognizing a shutdown, see Shutting Down an Schannel Connection.

When you use the Schannel SSP, DecryptMessage (General) returns SEC_I_RENEGOTIATE when the message sender wants to renegotiate the connection (security context). An application handles a requested renegotiation by calling AcceptSecurityContext (General) (server side) or InitializeSecurityContext (General) (client side) and passing in empty input buffers. After this initial call returns a value, proceed as though your application were creating a new connection. For more information, see Creating an Schannel Security Context.

For information about interoperating with GSSAPI, see SSPI/Kerberos Interoperability with GSSAPI.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Sspi.h (include Security.h)

Library

Secur32.lib

DLL

Secur32.dll

See also

SSPI Functions
EncryptMessage (General)
SecBuffer
SecBufferDesc

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.