AD FS and certificate KeySpec property Information
Key Specification (“KeySpec”) is a property associated with a certificate and key. It specifies whether a private key associated with a certificate can be used for signing, encryption, or both.
An incorrect KeySpec value can cause AD FS and Web Application Proxy errors such as:
- Failure to establish a SSL/TLS connection to AD FS or the Web Application Proxy, with no AD FS events logged (though SChannel 36888 and 36874 events may be logged)
- Failure to login at the AD FS or WAP forms based authentication page, with no error message shown on the page.
You may see the following in the event log:
Log Name: AD FS Tracing/Debug Source: AD FS Tracing Date: 2/12/2015 9:03:08 AM Event ID: 67 Task Category: None Level: Error Keywords: ADFSProtocol User: S-1-5-21-3723329422-3858836549-556620232-1580884 Computer: ADFS1.contoso.com Description: Ignore corrupted SSO cookie.
What causes the problem
The KeySpec property identifies how a key generated or retrieved by Microsoft CryptoAPI (CAPI), from a Microsoft legacy Cryptographic Storage Provider (CSP), can be used.
A KeySpec value of 1, or AT_KEYEXCHANGE, can be used for signing and encryption. A value of 2, or AT_SIGNATURE, is only used for signing.
The most common KeySpec mis-configuration is using a value of 2 for a certificate other than the token signing certificate.
For certificates whose keys were generated using Cryptography Next Generation (CNG) providers, there is no concept of key specification, and the KeySpec value will always be zero.
See how to check for a valid KeySpec value below.
An example of a legacy CSP is the Microsoft Enhanced Cryptographic Provider.
Microsoft RSA CSP key blob format includes an algorithm identifier, either CALG_RSA_KEYX or CALG_RSA_SIGN, respectively, to service requests for either AT_KEYEXCHANGE **or **AT_SIGNATURE keys.
The RSA key algorithm identifiers map to KeySpec values as follows
|Provider supported algorithm||Key Specification value for CAPI calls|
|CALG_RSA_KEYX : RSA key that can be used for signing and decryption||AT_KEYEXCHANGE (or KeySpec=1)|
|CALG_RSA_SIGN : RSA signature only key||AT_SIGNATURE (or KeySpec=2)|
KeySpec values and associated meanings
The following are the meanings of the various KeySpec values:
|Keyspec value||Means||Recommended AD FS use|
|0||The certificate is a CNG cert||SSL certificate only|
|1||For a legacy CAPI (non-CNG) cert, the key can be used for signing and decryption||SSL, token signing, token decrypting, service communication certificates|
|2||For a legacy CAPI (non-CNG) cert, the key can be used only for signing||not recommended|
How to check the KeySpec value for your certificates / keys
To see a certificates value you can use the certutil command line tool.
The following is an example: certutil –v –store my. This will dump the certificate information to the screen.
Under CERT_KEY_PROV_INFO_PROP_ID look for two things:
- ProviderType: this denotes whether the certificate uses a legacy Cryptographic Storage Provider (CSP) or a Key Storage Provider based on newer Certificate Next Generation (CNG) APIs. Any non-zero value indicates a legacy provider.
KeySpec: The following are valid KeySpec values for an AD FS certificate:
Legacy CSP provider (ProviderType not equal to 0):
AD FS Certificate Purpose Valid KeySpec Values Service Communication 1 Token Decrypting 1 Token Signing 1 and 2 SSL 1
CNG provider (ProviderType = 0):
AD FS Certificate Purpose Valid KeySpec Values SSL 0
How to change the keyspec for your certificate to a supported value
Changing the KeySpec value does not require the certificate to be re-generated or re-issued by the Certificate Authority. The KeySpec can be changed by re-importing the complete certificate and private key from a PFX file into the certificate store using the steps below:
- First, check and record the private key permissions on the existing certificate so that they can be re-configured if necessary after the re-import.
- Export the certificate including private key to a PFX file.
- Perform the following steps for each AD FS and WAP server
- Delete the certificate (from the AD FS / WAP server)
- Open an elevated PowerShell command prompt and import the PFX file on each AD FS and WAP server using the cmdlet syntax below, specifying the AT_KEYEXCHANGE value (which works for all AD FS certificate purposes):
- C:>certutil –importpfx certfile.pfx AT_KEYEXCHANGE
- Enter PFX password
- Once the above completes, do the following
- check the private key permissions
- restart the adfs or wap service
We'd love to hear your thoughts. Choose the type you'd like to provide:
Our feedback system is built on GitHub Issues. Read more on our blog.