SslEnumCipherSuites function

Artikel
05/04/2022

The SslEnumCipherSuites function enumerates the cipher suites supported by a Secure Sockets Layer protocol (SSL) protocol provider.

Syntax

SECURITY_STATUS WINAPI SslEnumCipherSuites(
  _In_     NCRYPT_PROV_HANDLE      hSslProvider,
  _In_opt_ NCRYPT_KEY_HANDLE       hPrivateKey,
  _Out_    NCRYPT_SSL_CIPHER_SUITE **ppCipherSuite,
  _Inout_  PVOID                   *ppEnumState,
  _In_     DWORD                   dwFlags
);

Parameters

hSslProvider [in]

The handle of the SSL protocol provider instance.

hPrivateKey [in, optional]

The handle of a private key. When a private key is specified, SslEnumCipherSuites enumerates the cipher suites that are compatible with the private key. For example, if the private key is a DSS key, then only the DSS_DHE cipher suites are returned. If the private key is an RSA key, but it does not support raw decryption operations, then the SSL2 cipher suites are not returned.

Set this parameter to NULL when you are not specifying a private key.

Note

A hPrivateKey handle is obtained by calling the SslOpenPrivateKey function. Handles obtained from the NCryptOpenKey function are not supported.

ppCipherSuite [out]

A pointer to a NCRYPT_SSL_CIPHER_SUITE structure to receive the address of the next cipher suite in the list.

ppEnumState [in, out]

A pointer to a buffer that indicates the current position in the list of cipher suites.

Set the pointer to NULL on the first call to SslEnumCipherSuites. On each subsequent call, pass the unmodified value back to SslEnumCipherSuites.

When there are no more cipher suites available, you should free ppEnumState by calling the SslFreeBuffer function.

dwFlags [in]

This parameter is reserved for future use.

Return value

If the function succeeds, it returns zero.

If the function fails, it returns a nonzero error value.

Possible return codes include, but are not limited to, the following.

Return code/value	Description
NTE_NO_MEMORY 0x8009000EL	Not enough memory is available to allocate necessary buffers.
NTE_INVALID_HANDLE 0x80090026L	One of the provided handles is not valid.
NTE_NO_MORE_ITEMS 0x8009002AL	No additional cipher suites are supported.

Remarks

To enumerate all cipher suites supported by the SSL provider, call the SslEnumCipherSuites function in a loop until NTE_NO_MORE_ITEMS is returned.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Header	Sslprovider.h
Library	Ncrypt.lib
DLL	Ncrypt.dll

Dela via