SCH_CREDENTIALS structure (schannel.h)
The SCH_CREDENTIALS structure contains initialization information for an Schannel credential.
Syntax
typedef struct _SCH_CREDENTIALS {
DWORD dwVersion;
DWORD dwCredFormat;
DWORD cCreds;
PCCERT_CONTEXT *paCred;
HCERTSTORE hRootStore;
DWORD cMappers;
_HMAPPER **aphMappers;
struct _HMAPPER;
DWORD dwSessionLifespan;
DWORD dwFlags;
DWORD cTlsParameters;
PTLS_PARAMETERS pTlsParameters;
} SCH_CREDENTIALS, *PSCH_CREDENTIALS;
Members
dwVersion
Set to SCH_CREDENTIALS_VERSION.
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 SCH_CREDENTIALS 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 SCH_CREDENTIALS structure points to a SCHANNEL_CERT_HASH_STORE structure. |
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.
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
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. |
cTlsParameters
The count of entries in the pTlsParameters array.
It is an error to specify more than SCH_CRED_MAX_SUPPORTED_PARAMETERS.
pTlsParameters
Array of pointers to the TLS_PARAMETERS structures that indicate TLS parameter restrictions, if any. If no restrictions are specified, the system defaults are used. It is recommended that applications rely on the system defaults.
It is an error to include more than one TLS_PARAMETERS structure with cAlpnIds == 0 and rgstrAlpnIds == NULL.
Remarks
To use the SCH_CREDENTIALS structure, define SCHANNEL_USE_BLACKLISTS along with UNICODE_STRING and PUNICODE_STRING. Alternatively, include Ntdef.h, SubAuth.h or Winternl.h.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 10 1809 [desktop apps only] |
| Minimum supported server | Windows Server 1809 [desktop apps only] |
| Header | schannel.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