Platform SDK: Logon Authentication

DecryptMessage

The DecryptMessage function decrypts a message. Some packages do not have messages to encrypt/decrypt, but rather an integrity hash to be provided and checked.

SECURITY_STATUS DecryptMessage(
  PCtxtHandle phContext,     // context to use
  PSecBufferDesc pMessage,   // buffer containing the message to decrypt
  ULONG MessageSeqNo,        // expected sequence number
  PULONG pfQOP               // quality of protection
);

Parameters

phContext

[in] Handle to the security context to be used to decrypt the message.

pMessage

[in/out] 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.

MessageSeqNo

[in] Specifies 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.

pfQOP

[out] Pointer to a ULONG variable that receives package-specific flags indicating the quality of protection.

The following flag is defined for use with the Kerberos protocol.

Flag Description

KERB_WRAP_NO_ENCRYPT Message was not encrypted, but a header/trailer was produced.

Flag	Description
`KERB_WRAP_NO_ENCRYPT`	Message was not encrypted, but a header/trailer was produced.

Return Values

If the function verifies that the message was received in the correct sequence, the return value is SEC_E_OK.

If the function fails to decrypt the message, the return value can be one of the following error codes.

Value	Meaning
SEC_E_OUT_OF_SEQUENCE	The message was not received in the correct sequence.
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 again.
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 or InitializeSecurityContext, passing empty input buffers.
SEC_E_CONTEXT_EXPIRED	The remote party closed the connection. Call EncryptMessage with an empty input buffer, send the output data (if any) to the remote party, and delete the security context.

Remarks

Sometimes an application will read data from the remote party, attempt to decrypt it with DecryptMessage, and discover that DecryptMessage succeeded but the output buffers are empty. This is normal behavior, and applications must be able to deal with it.

The prototype for this function can be found in Sspi.h.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Sspi.h; include Security.h.
  Library: Use Secur32.lib.

DecryptMessage

Parameters

Return Values

Remarks

Requirements

See Also