Platform SDK: Logon Authentication

SCHANNEL_CRED

The SCHANNEL_CRED structure contains the data for an Schannel credential.

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           reserved;
} SCHANNEL_CRED, *PSCHANNEL_CRED;

Members

dwVersion

Set to SCHANNEL_CRED_VERSION (currently 4).

cCreds

Number of elements in the paCred array.

paCred

Array of Microsoft® CryptoAPI CERT_CONTEXT structure pointers. Each pointer specifies a certificate and, through it, access to a private key to be used to authenticate the application/user. There will typically be one entry in this array 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 will supply a certificate later if needed.

hRootStore

Handle to a CryptoAPI certificate store that contains one or more self-signed root certificates of certification authorities (CAs) trusted by the application. This field is optional, and can only be used by server-side applications that require client authentication.

Client-side applications set this field to NULL.

cMappers

Number of mapping functions in the following array.

aphMappers

Array of certificate mapping functions, used by Schannel to map client certificates to operating system user accounts. This field is optional, and can only be used by server-side applications that require client authentication.

When Schannel receives a certificate from a remote client, it calls each of these certificate mapping functions in turn until one succeeds. In this case, the certificate mapper will return a user token to Schannel that will later be passed to the application through the QuerySecurityContextToken function.

Client-side applications pass zero and NULL in these fields.

cSupportedAlgs

Number of algorithms in the following array.

palgSupportedAlgs

Array of algorithm identifiers to be supported by connections made from this credential.

If cSupportedAlgs is zero or palgSupportedAlgs is NULL, Schannel uses the system defaults.

grbitEnabledProtocols

Array of bits representing the protocols to be supported by connections made from this credential. This field is only used by the Schannel Microsoft Unified Security Protocol Provider security package.

The global system settings (in HKEY_LOCAL_MACHINE) take precedence over this value. For example, if SSL3 is disabled in the registry, it cannot be enabled through this bit field. The flags used with this field include:

SS_PROT_PCT1_SERVER
SP_PROT_PCT1_CLIENT
SP_PROT_SSL2_CLIENT
SP_PROT_SSL2_SERVER
SP_PROT_SSL3_CLIENT
SP_PROT_SSL3_SERVER
SP_PROT_TLS1_CLIENT
SP_PROT_TLS1_SERVER

If this is zero, Schannel selects the protocol.

dwMinimumCipherStrength

Minimum bulk encryption cipher strength (in bits) to be allowed for connections.

If zero, Schannel uses its default setting.

dwMaximumCipherStrength

Maximum bulk encryption cipher strength (in bits) to be allowed for connections.

If zero, Schannel uses its default setting.

dwSessionLifespan

DWORD indicating the maximum life span of the credential.

dwFlags

Can be zero or any one of the following values:

SCH_CRED_NO_SYSTEM_MAPPER: If set, Schannel does not attempt to map received client certificate chains to an operating system user account using the built-in system certificate mapper. This flag is intended for use by server applications only.
This flag is ignored by versions of Schannel earlier than Windows 2000.
SCH_CRED_NO_SERVERNAME_CHECK: If set, the target name passed in is not compared with the subject names embedded in the certificates in the received server certificate chain.
This flag is intended for use by client applications only. It is ignored by versions of Schannel earlier than Windows 2000 or if the SCH_CRED_MANUAL_CRED_VALIDATION flag is also set.
SCH_CRED_MANUAL_CRED_VALIDATION: If set, Schannel does not attempt to validate the received server certificate chain. This flag is intended for use by client applications only.
This flag is ignored by versions of Schannel earlier than Windows 2000, but client applications that validate certificate chains must specify this flag to run correctly on Windows 2000.
SCH_CRED_NO_DEFAULT_CREDS: If set and the server requests client authentication, Schannel will not attempt to acquire a suitable default client certificate chain. This flag is intended for use by client applications only.
This flag is ignored by versions of Schannel earlier than Windows 2000, but client applications that will manually specify certificate chains must specify this flag to run correctly on Windows 2000.
SCH_CRED_AUTO_CRED_VALIDATION: This flag is the opposite of SCH_CRED_MANUAL_CRED_VALIDATION. Conservatively-written client applications always specify one flag or the other.
SCH_CRED_USE_DEFAULT_CREDS: This flag is the opposite of SCH_CRED_NO_DEFAULT_CREDS. Conservatively-written client applications always specify one flag or the other.

reserved

Reserved. Must be zero.

Requirements

  Windows NT/2000: Requires Windows NT 3.51 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Schannel.h; include Schnlsp.h.

SCHANNEL_CRED

Members

Requirements

See Also