SCHANNEL_CRED structure (schannel.h)
Note
The SCHANNEL_CRED structure is deprecated. You should use SCH_CREDENTIALS instead.
The SCHANNEL_CRED structure contains the data for an Schannel credential.
Syntax
typedef struct _SCHANNEL_CRED {
DWORD dwVersion;
DWORD cCreds;
PCCERT_CONTEXT *paCred;
HCERTSTORE hRootStore;
DWORD cMappers;
_HMAPPER **aphMappers;
struct _HMAPPER;
DWORD cSupportedAlgs;
ALG_ID *palgSupportedAlgs;
DWORD grbitEnabledProtocols;
DWORD dwMinimumCipherStrength;
DWORD dwMaximumCipherStrength;
DWORD dwSessionLifespan;
DWORD dwFlags;
DWORD dwCredFormat;
} SCHANNEL_CRED, *PSCHANNEL_CRED;
Members
dwVersion
Set to SCHANNEL_CRED_VERSION.
cCreds
The number of structures in the paCred array.
paCred
An array of pointers to CERT_CONTEXT structures. Each pointer specifies a certificate that contains a private key to be used in authenticating the application. Typically, this array contains one structure for each key exchange method supported by the application.
Client applications often pass in an empty list and either depend on Schannel to find an appropriate certificate or create a certificate later if needed.
hRootStore
Optional. Valid for server applications only. Handle to a certificate store that contains self-signed root certificates for certification authorities (CAs) trusted by the application. This member is used only by server-side applications that require client authentication.
cMappers
Reserved.
aphMappers
Reserved.
_HMAPPER
cSupportedAlgs
Number of algorithms in the palgSupportedAlgs array.
palgSupportedAlgs
Optional. A pointer to an array of ALG_ID algorithm identifiers that represent the algorithms supported by connections made with credentials acquired using this structure. If cSupportedAlgs is zero or palgSupportedAlgs is NULL, Schannel uses the system defaults.
Currently, the algorithm identifiers CALG_AES, CALG_AES_128, and CALG_AES_256 are not supported.
grbitEnabledProtocols
Optional. A DWORD that contains a bit string that represents the protocols supported by connections made with credentials acquired by using this structure. If this member is zero, Schannel selects the protocol. For new development, applications should set grbitEnabledProtocols to zero and use the protocol versions enabled on the system by default.
This member is used only by the Microsoft Unified Security Protocol Provider security package.
The global system registry settings take precedence over this value. For example, if SSL3 is disabled in the registry, it cannot be enabled using this member.
This member can contain any of the following flags.
dwMinimumCipherStrength
Minimum bulk encryption cipher strength, in bits, allowed for connections.
If this member is zero, Schannel uses the system default. If this member is –1, only the SSL3/TLS MAC–only cipher suites (also known as NULL cipher) are enabled.
dwMaximumCipherStrength
Maximum bulk encryption cipher strength, in bits, allowed for connections.
If this member is zero, Schannel uses the system default.
If this member is –1, only the SSL3/TLS MAC–only cipher suites (also known as NULL cipher) are enabled. In this case, dwMinimumCipherStrength must be set to –1.
dwSessionLifespan
The number of milliseconds that Schannel keeps the session in its session cache. After this time has passed, any new connections between the client and the server require a new Schannel session. Set the value of this member to zero to use the default value of 36000000 milliseconds (ten hours).
dwFlags
Contains bit flags that control the behavior of Schannel. This member can be zero or a combination of the following values.
| Value | Meaning |
|---|---|
|
Client only.
This flag is the opposite of SCH_CRED_MANUAL_CRED_VALIDATION and is part of the default behavior of Schannel. |
|
Instruct Schannel to pass the CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL flag to the CertGetCertificateChain function when validating the specified credentials during a call to AcquireCredentialsHandle (Schannel).
Windows Server 2003 and Windows XP/2000: This flag is not supported. |
|
Server only.
If this flag is set, then full handshakes performed with this credential will not allow reconnects. A cache entry is created, so the session can be made resumable later by using the ApplyControlToken function. |
|
When checking for revoked certificates, ignore CRYPT_E_NO_REVOCATION_CHECK errors. For additional restrictions, see Remarks. |
|
When checking for revoked certificates, ignore CRYPT_E_REVOCATION_OFFLINE errors. For additional restrictions, see Remarks. |
|
Client only.
Prevent Schannel from validating the received server certificate chain. |
|
Client only.
Prevent Schannel from attempting to automatically supply a certificate chain for client authentication. |
|
Client only.
Prevent Schannel from comparing the supplied target name with the subject names in server certificates. |
|
Server only.
Prevent Schannel from using the built-in system certificate mapping functions to map client certificates to a user account. |
|
When validating a certificate chain, check all certificates for revocation. For additional restrictions, see Remarks. |
|
When validating a certificate chain, do not check the root for revocation. For additional restrictions, see Remarks. |
|
When validating a certificate chain, check only the last certificate for revocation. For additional restrictions, see Remarks. |
|
Client only.
Schannel attempts to automatically supply a certificate chain for client authentication. This value is the opposite of SCH_CRED_NO_DEFAULT_CREDS. |
|
Instruct Schannel to split data to be encrypted into two separate records to counter weakness present in the SSL/TLS protocol when used with symmetric cipher suite using cipher block chaining mode. For more information, see "Vulnerability in SSL/TLS Could Allow Information Disclosure" in the Help and Support Knowledge Base at http://support.microsoft.com/kb/2643584.
Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP and Windows XP/2000: This flag is not supported. |
|
Schannel sends the root certificate as part of the certificate message.
Note The root certificate sent over the network by the Schannel client or server is not to be trusted. It should be validated against a trusted hash of the root certificate.
|
|
Instructs Schannel to disable known weak cryptographic algorithms, cipher suites, and SSL/TLS protocol versions that may be otherwise enabled for better interoperability. |
|
Instructs Schannel to select only PSK cipher suites and disable all other cipher suites. |
dwCredFormat
Kernel-mode Schannel supports the following values.
Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP and Windows XP/2000: This flag is not supported and must be zero.
| Value | Meaning |
|---|---|
|
The paCred member of the SCHANNEL_CRED structure passed in must be a pointer to a byte array of length 20 that contains the certificate thumbprint. The certificate is assumed to be in the "MY" store of the local computer. |
|
The paCred member of the SCHANNEL_CRED structure points to a SCHANNEL_CERT_HASH_STORE structure. |
Remarks
The following certificate revocation flags are mutually exclusive.
- SCH_CRED_REVOCATION_CHECK_CHAIN
- SCH_CRED_REVOCATION_CHECK_END_CERT
- SCH_CRED_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT
To customize certificate revocation error reporting for Schannel, use the following flags:
- SCH_CRED_IGNORE_NO_REVOCATION_CHECK
- SCH_CRED_IGNORE_REVOCATION_OFFLINE
When Schannel checks the revocation status of a certificate chain, these flags instruct it to ignore any CRYPT_E_NO_REVOCATION_CHECK and CRYPT_E_REVOCATION_OFFLINE errors, respectively. These flags are ignored if no certificate revocation flag is set.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8.1 [desktop apps only] |
| Minimum supported server | Windows Server 2012 R2 [desktop apps only] |
| Header | schannel.h (include Schnlsp.h) |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for