Export (0) Print
Expand All
Expand Minimize

SCHANNEL_CRED structure

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;
  struct _HMAPPER  **aphMappers;
  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.

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, use Transport Layer Security 1.0.

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.

ValueMeaning
SP_PROT_PCT1_SERVER
0x00000001

Private Communications Technology 1.0 server side. (Obsolete.)

SP_PROT_PCT1_CLIENT
0x00000002

Private Communications Technology 1.0 client side. (Obsolete.)

SP_PROT_SSL2_SERVER
0x00000004

Secure Sockets Layer 2.0 server side. Superseded by SP_PROT_TLS1_SERVER.

Important  Secure Sockets Layer 2.0 and Transport Layer Security 1.2 flags are mutually exclusive.

SP_PROT_SSL2_CLIENT
0x00000008

Secure Sockets Layer 2.0 client side. Superseded by SP_PROT_TLS1_CLIENT.

Important  Secure Sockets Layer 2.0 and Transport Layer Security 1.2 flags are mutually exclusive.

SP_PROT_SSL3_SERVER
0x00000010

Secure Sockets Layer 3.0 server side.

SP_PROT_SSL3_CLIENT
0x00000020

Secure Sockets Layer 3.0 client side.

SP_PROT_TLS1_SERVER
0x00000040

Transport Layer Security 1.0 server side.

SP_PROT_TLS1_CLIENT
0x00000080

Transport Layer Security 1.0 client side.

SP_PROT_TLS1_0_SERVER
SP_PROT_TLS1_SERVER

Transport Layer Security 1.0 server side.

SP_PROT_TLS1_0_CLIENT
SP_PROT_TLS1_CLIENT

Transport Layer Security 1.0 client side.

SP_PROT_TLS1_1_SERVER
0x00000100

Transport Layer Security 1.1 server side.

SP_PROT_TLS1_1_CLIENT
0x00000200

Transport Layer Security 1.1 client side.

SP_PROT_TLS1_2_SERVER
0x00000400

Transport Layer Security 1.2 server side.

Important  Secure Sockets Layer 2.0 and Transport Layer Security 1.2 flags are mutually exclusive.

SP_PROT_TLS1_2_CLIENT
0x00000800

Transport Layer Security 1.2 client side.

Important  Secure Sockets Layer 2.0 and Transport Layer Security 1.2 flags are mutually exclusive.

 

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.

ValueMeaning
SCH_CRED_AUTO_CRED_VALIDATION
0x00000020

Client only.

This flag is the opposite of SCH_CRED_MANUAL_CRED_VALIDATION and is part of the default behavior of Schannel.

SCH_CRED_CACHE_ONLY_URL_RETRIEVAL_ON_CREATE
0x00020000

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.

SCH_DISABLE_RECONNECTS
0x00000080

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.

SCH_CRED_IGNORE_NO_REVOCATION_CHECK
0x00000800

When checking for revoked certificates, ignore CRYPT_E_NO_REVOCATION_CHECK errors. For additional restrictions, see Remarks.

SCH_CRED_IGNORE_REVOCATION_OFFLINE
0x00001000

When checking for revoked certificates, ignore CRYPT_E_REVOCATION_OFFLINE errors. For additional restrictions, see Remarks.

SCH_CRED_MANUAL_CRED_VALIDATION
0x00000008

Client only.

Prevent Schannel from validating the received server certificate chain.

SCH_CRED_NO_DEFAULT_CREDS
0x00000010

Client only.

Prevent Schannel from attempting to automatically supply a certificate chain for client authentication.

SCH_CRED_NO_SERVERNAME_CHECK
0x00000004

Client only.

Prevent Schannel from comparing the supplied target name with the subject names in server certificates.

SCH_CRED_NO_SYSTEM_MAPPER
0x00000002

Server only.

Prevent Schannel from using the built-in system certificate mapping functions to map client certificates to a user account.

SCH_CRED_REVOCATION_CHECK_CHAIN
0x00000200

When validating a certificate chain, check all certificates for revocation. For additional restrictions, see Remarks.

SCH_CRED_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT
0x00000400

When validating a certificate chain, do not check the root for revocation. For additional restrictions, see Remarks.

SCH_CRED_REVOCATION_CHECK_END_CERT
0x00000100

When validating a certificate chain, check only the last certificate for revocation. For additional restrictions, see Remarks.

SCH_CRED_USE_DEFAULT_CREDS
0x00000040

Client only.

Schannel attempts to automatically supply a certificate chain for client authentication. This value is the opposite of SCH_CRED_NO_DEFAULT_CREDS.

SCH_SEND_AUX_RECORD
0x00200000

Instruct Schannel to split data to be encrypted into two separate records to counter weakness present in the SSL/TLS procotol 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.

SCH_SEND_ROOT_CERT
0x00040000

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.

SCH_USE_STRONG_CRYPTO
0x00400000

Instructs Schannel to disable known weak cryptographic algorithms, cipher suites, and SSL/TLS protocol versions that may be otherwise enabled for better interoperability.

 

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.

ValueMeaning
SCH_CRED_FORMAT_CERT_HASH
0x00000001

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.

SCH_CRED_FORMAT_CERT_HASH_STORE
0x00000002

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

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

QuerySecurityContextToken

 

 

Community Additions

ADD
Show:
© 2014 Microsoft