Private key protection

Introduction

FAS certificates are stored in an embedded database on the FAS server. The private keys associated with FAS certificates are stored under the Network Service account of the FAS server. By default, the keys are non-exportable, 2048-bit RSA, created and stored in the Microsoft Software Key Storage Provider.

Using FAS PowerShell commands PowerShell cmdlets, it’s possible to change the properties and storage location of the private keys.

Note:

FAS configuration and certificates are stored locally on the FAS server. The data is not shared between FAS servers.

In FAS releases before Citrix Virtual Apps and Desktops 2411, private key properties were configured by editing the XML file at %programfiles%\Citrix\Federated Authentication Service\Citrix.Authentication.FederatedAuthenticationService.exe.config. This has been superseded by PowerShell commands, which provide more flexibility and can be applied without restarting the FAS server. Additionally, unlike the XML file settings, configuration made using PowerShell is retained when the FAS server is upgraded. Therefore, configuration using the XML file for the following settings is no longer supported:

• Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.KeyProtection
• Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderLegacyCsp
• Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderName
• Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderType
• Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.KeyLength

See the section, Upgrading from versions of FAS before Citrix Virtual Apps and Desktops 2411.

Information about FAS certificates and templates

There are two types of certificates held by FAS: the authorization certificate, of which there is normally one instance, and the user certificates.

Note:

The FAS authorization certificate is also sometimes referred to as an Registration Authority or Request Agent (RA) certificate.

FAS uses certificate templates when requesting certificates, as described in the following section. While FAS does specify the name of a template in certificate requests, it does not read the content of the template. Therefore changing the template’s settings does not influence the certificate requests made by FAS. Changing certain properties of the template affects the certificate generated by the CA. For example, you can change the validity period using the template.

FAS authorization certificate

This certificate is created when you configure FAS. You can use the FAS administration console’s Authorize or Reauthorize button to request a new authorization certificate.

It’s also possible to use PowerShell commands, which provide more flexibility:

• New-FasAuthorizationCertificate: This command behaves similarly to the FAS administration console, except it’s possible to specify the certificate templates to use in the authorization process.
• New-FasAuthorizationCertificateRequest: This command creates an offline request for an authorization certificate; Offline authorization.

The authorization certificate is also sometimes referred to as an RA certificate, because FAS is acting as a registration authority, that is requesting certificates on behalf of a user. The certificate has the enhanced key usage Certificate Request Agent, that allows it to be used as an authorization credential when requesting FAS user certificates.

By default, the authorization process uses the following templates:

• Citrix_RegistrationAuthority_ManualAuthorization: The certificate created using this template is temporary and short lived, used to bootstrap the authorization process;
• Citrix_RegistrationAuthority: The certificate created using this template has a long validity, and is stored by the FAS server.

Authorizing FAS results in the following steps:

1. FAS creates a keypair, and sends a Certificate Signing Request (CSR) to the CA, specifying the public key of the keypair and the template Citrix_RegistrationAuthority_ManualAuthorization.

2. The template’s issuance requirements specify that the CSR must be manually approved by the CA administrator.

3. Once the CA administrator has approved the CSR, the CA creates a certificate which FAS retrieves. This certificate has a short validity of one day and is only used for the following step. Once used, FAS destroys the certificate and its keypair.

4. FAS creates another keypair, and sends a second CSR to the CA, specifying the public key of this keypair and the template Citrix_RegistrationAuthority. The request is authorized by and signed with the certificate from the previous step.

5. The CA automatically issues the certificate, FAS retrieves the certificate, and FAS is now Authorized. By default, this authorization certificate has a validity of two years.

The settings used to create the keypairs mentioned before can be viewed using this PowerShell command:

Get-FasKeyConfig -Address localhost -CertificateType ra

FAS user certificates

FAS creates user certificates to sign users in to VDAs.

When FAS creates a user certificate, the following steps occur:

• FAS creates a key pair, and sends a CSR to the CA, specifying the public key of the keypair, the identity of the user, and by default, the template Citrix_SmartcardLogon (the template used is configurable).
• The CSR is signed using the FAS authorization certificate.
• Citrix_SmartcardLogon template has issuance requirement Application Policy: Certificate Request Agent. As this attribute is present in the FAS authorization certificate, the CA issues the user certificate automatically.
• FAS retrieves the certificate, and stores it in an embedded database on the FAS server.
• By default, the certificate has a validity of one week.

Later, the user certificate is made available to the VDA to sign the user in.

The settings used to create the keypair mentioned before can be viewed using the following PowerShell command:

Get-FasKeyConfig -Address localhost -CertificateType user

Private key storage options

FAS can be configured to create and store keypairs in three categories of storage:

• Software: Normally using Microsoft Software Key Storage Provider, which is secured by software only; the data is stored on the disk.
• Trusted Platform Module (TPM): The TPM can be physical hardware on the computer, or a virtual TPM provided by a hypervisor.
• Hardware Security Module (HSM): This is a hardware peripheral or network device designed to securely store cryptographic keys.

Note:

There is a trade-off to consider. Hardware storage may be more secure, but is often less performant, especially when creating and storing a large number of user certificate keypairs.

The private key associated with the FAS authorization certificate is particularly sensitive, as the certificate’s policy allows whoever possesses the private key to authorize certificate requests, for any user. As a consequence, whoever controls this key can connect to the environment as any user.

Note:

Microsoft CAs can be configured to restrict the power of the FAS authorization certificate, including the set of users for whom certificates can be issued. See Delegated enrollment agents.

For this reason, FAS allows you to configure the private key properties for authorization and user certificates independently.

Some typical configurations are as follows:

Note:

A hardware TPM is not recommended for user keys. Use TPM for the authorization certificate key only. If you plan to run your FAS server in a virtualized environment, check with your hypervisor vendor whether TPM virtualization is supported.

Key configuration PowerShell commands

The commands relating to the configuration of private keys are as follows:

• Get-FasKeyConfig
• Set-FasKeyConfig
• Reset-FasKeyConfig
• Test-FasKeyConfig

For more information, see PowerShell cmdlets.

The key configuration for authorization and user certificates is independent, specified by the CertificateType argument. For example, to get the private key configuration used when requesting an authorization certificate (RA certificate):

Get-FasKeyConfig -Address localhost -CertificateType ra

To get the private key configuration used when requesting a user certificate:

Get-FasKeyConfig -Address localhost -CertificateType user

You can use Set-FasKeyConfig and Get-FasKeyConfig to set and inspect the following private key properties:

In addition, Set-FasKeyConfig can be used with the following switches, provided for convenience:

Microsoft Software Key Storage Provider is the provider usually used to create and store keys on disk.

Microsoft Platform Crypto Provider is the provider usually used to create and store keys in a TPM.

Get-FasKeyConfig also provides fields, which help confirm which provider and algorithm are being used:

You can restore the settings to the defaults using Reset-FasKeyConfig.

Reset-FasKeyConfig -Address localhost -CertificateType ra
Reset-FasKeyConfig -Address localhost -CertificateType user
<!--NeedCopy-->

Note:

Changes made to the Private key configuration (using Set-FasKeyConfig or Reset-FasKeyConfig) apply immediately to newly created certificates. However, existing authorization and user certificates with a different configuration are not affected.

You can remove existing certificates by deauthorizing your FAS service from the administration console, or by using PowerShell commands in Deauthorizing FAS and deleting FAS certificates.

Any pre-generated keys in the key pool which do not conform to the current user key configuration are discarded.

Configuration scenario examples

In each example, set the key configuration using the PowerShell provided before authorizing your FAS service, as the existing certificates are unaffected by any configuration change.

If you already have authorization or user certificates with the wrong key configuration you can remove them by Inspecting FAS certificates and Deauthorizing FAS and deleting FAS certificates.

If your FAS server is in a live deployment, consider putting it into maintenance mode while making configuration changes Maintenance mode.

Example 1 - Store all keys in Microsoft Software Key Storage Provider

As this is by default, no additional configuration is required.

If you have changed your key configuration previously, you can revert to using Microsoft Software Key Storage Provider with the following commands:

Set-FasKeyConfig -Address localhost -CertificateType ra -UseDefaultSoftwareProvider
Set-FasKeyConfig -Address localhost -CertificateType user -UseDefaultSoftwareProvider
<!--NeedCopy-->

You can use Reset-FasKeyConfig to revert to Microsoft Software Key Storage Provider and additionally restore all the other key configuration settings to the defaults.

Example 2 - Store the authorization certificate key in a TPM

This example illustrates storing the FAS authorization certificate key in a TPM (real or virtual), while the user certificate keys are stored in the Microsoft Software Key Storage Provider.

Although FAS can generate user certificates with TPM protected keys, the TPM hardware may be too slow or size constrained for large deployments.

Use the following PowerShell commands:

Set-FasKeyConfig -Address localhost -CertificateType ra -UseDefaultTpmProvider
Set-FasKeyConfig -Address localhost -CertificateType user -UseDefaultSoftwareProvider
<!--NeedCopy-->

Example 3 - Store all keys in an HSM

This example illustrates using an HSM to store both authorization certificate and user certificate private keys. This example assumes a configured HSM. Your HSM will have a provider name. For example, HSM Vendor Key Storage Provider.

Use the following PowerShell commands (replace the example text with the actual name of your HSM’s Provider):

Set-FasKeyConfig -Address localhost -CertificateType ra -Provider "HSM Vendor Key Storage Provider"
Set-FasKeyConfig -Address localhost -CertificateType user -Provider "HSM Vendor Key Storage Provider"
<!--NeedCopy-->

Example 4 - Use Elliptic Curve keys

By default, FAS generates RSA keys. In this example, Elliptic curve (ECC) keys are configured for both the authorization certificate and user certificates.

The example uses different key lengths. The authorization certificate is configured with a 384-bit key, and user certificates are configured with a 256-bit key.

Set-FasKeyConfig -Address localhost -CertificateType ra -EllipticCurve $true -Length 384
Set-FasKeyConfig -Address localhost -CertificateType user -EllipticCurve $true -Length 256
<!--NeedCopy-->

At this point, authorization and user certificate requests may be rejected by the CA because the minimum key size in the FAS certificate templates is set to 1024 bits by default.

Therefore, for this example, it’s necessary to change the minimum key size in the templates as follows:

• Citrix_RegistrationAuthority_ManualAuthorization and Citrix_RegistrationAuthority: Change the minimum key size to 384 (or smaller)
• Citrix_SmartcardLogon: Change the minimum key size to 256 (or smaller)

To edit the templates, run mmc.exe, and add the Certificate Templates snap-in. Locate the template, and open its properties. The minimum key size setting is located in the Cryptography tab of the template’s properties.

Note:

User certificates with ECC keys are only supported on Windows VDAs running Citrix Virtual Apps and Desktops 2411 or later. ECC keys are not supported on Linux VDAs.

Testing the private key configuration

Although the Set-FasKeyConfig command does some validation, it’s still possible to set an invalid key configuration. For example, you may make a mistake in the Provider name of your HSM, or the key length you specify may not be supported by your hardware.

The command Test-FasKeyConfig can help. It attempts to create a keypair using the current key configuration, and reports success or failure. If a failure occurs, an indication of the failure reason is provided. If successful, the keypair is immediately destroyed.

The following PowerShell commands test the authorization and user key configuration respectively:

Test-FasKeyConfig -Address localhost -CertificateType ra
Test-FasKeyConfig -Address localhost -CertificateType user
<!--NeedCopy-->

Once you’ve authorized your FAS server and created a rule, you can additionally make a test CSR for a user certificate as follows:

Test-FasCertificateSigningRequest -Address localhost -UserPrincipalName user@example.com -Rule default

Replace «user@example.com>/> with a real UPN from your Active Directory deployment. The FAS rule is normally named default. But, if you prefer to test another rule that you have configured, specify that name instead.

If the CSR succeeds, FAS discards the resulting certificate.

Inspecting FAS certificates

You can use PowerShell to inspect a certificate’s properties and determine where the associated private key is stored.

Inspecting the authorization certificate

You can see the authorization certificate by clicking the authorization certificate link in the FAS administration console:

However, for more detailed information use PowerShell:

Get-FasAuthorizationCertificate -Address localhost -FullCertInfo

Several fields are returned, including PrivateKeyProvider, which contains an indication of the provider where the certificate was created and stored.

Inspecting user certifcates

You can get a list of all user certificates cached on the FAS server as follows:

Get-FasUserCertificate -Address localhost -KeyInfo $true

The KeyInfo parameter causes the output to contain further information about the private key associated with the certificate. In particular, the PrivateKeyProvider field indicates where the keypair associated with the certificate is stored (see the previous section for interpreting this value).

You can filter the set of certificates returned using various optional parameters, such as -UserPrincipalName.

The certificate field of the command output is a PEM encoded user certificate. Copy the text to a .crt file to display the certificate using the Windows certificate GUI as follows:

Upgrading from versions of FAS before Citrix Virtual Apps and Desktops 2411

In FAS releases before Citrix Virtual Apps and Desktops 2411, private key properties were configured by editing the XML file at

%programfiles%\Citrix\Federated Authentication Service\Citrix.Authentication.FederatedAuthenticationService.exe.config
<!--NeedCopy-->

This has been superseded by the PowerShell commands described in this document, which provide more flexibility and can be applied without restarting the FAS server.

Additionally, unlike the XML file settings, configuration done using PowerShell is retained when the FAS server is upgraded.

The XML file settings relevant to private key configuration are listed as follows, with their corresponding PowerShell parameters (as used in Get-FasKeyConfig and Set-FasKeyConfig):

The XML configuration defaults and the PowerShell defaults are functionally equivalent. That is, by default, properties of keypairs generated by FAS in this version and in versions before Citrix Virtual Apps and Desktops 2411 are the same.

Therefore, if you have not changed any of the preceding settings in the XML configuration file, you need not take any action when upgrading FAS.

However, if you have changed any of the preceding settings, upgrade FAS as follows:

• Place FAS into maintenance mode; Maintenance mode.
• Upgrade FAS in place simply by running the FAS installer; once upgrade, all previous settings will not be present in the XML file, and they cannot be configured in the XML file.
• Use the PowerShell command Set-FasKeyConfig, as described in Key configuration PowerShell commands, to set the FAS private key configuration as desired; consider the settings you need for your authorization and user certificates.
• Test your configuration, as described in Testing the private key configuration
• Take the FAS server out of maintenance mode

Next time you upgrade, the FAS private key configuration settings is retained, and there is no need to take any special action.

Cryptographic remoting

Private keys associated with FAS user certificates are never transfered to the VDA. Instead, when the VDA needs to use a user’s FAS certificate, either for signing in to the VDA, or for in-session use, the cryptographic request is remoted back to the FAS server. This improves security, because the private keys never leave FAS key storage (whether they are software storage, TPM, or HSM).

On Windows VDAs, this is achieved by using a pair of providers on the VDA. The application or operating system code making the cryptographic request is unaware that the operation is being remoted back to the FAS server.

Before Citrix Virtual Apps and Desktops 2411, the providers were Cryptographic Service Providers (CSPs) where applications and operating system code access was through the older Windows CAPI API. The providers were:

• CitrixLogonCsp.dll: for single sign-on to the VDA
• CitrixVirtualSmartcardCsp.dll: for in-session certificates

From Citrix Virtual Apps and Desktops 2411 onwards, additional Key Storage Providers (KSPs) are supplied on the VDA. Applications and operation system code access these with the newer Windows CNG API. The new providers are:

• CitrixLogonKsp.dll: for single sign-on to the VDA
• CitrixVirtualSmartcardKsp.dll: for in-session certificates

KSP is a more up-to-date way of exposing cryptographic operations to Windows applications, which provides more capabilities. For example:

• Certificates with ECC keys are supported
• Probabilistic Signature Scheme (PSS) padding is supported

KSP remoting is used (that is, remoting through the new KSPs) if both FAS and the VDA are running Citrix Virtual Apps and Desktops 2411 or later. Otherwise, the system falls back to use the older CSPs for remoting.

Disabling KSP remoting

In case of any compatibility issues, it’s possible to disable KSP remoting so that the older CSP remoting can always be used.

Use the following PowerShell:

Set-FasServer -Address localhost -KspRemoting $false

Maintenance mode

When performing changes to the configuration of a live FAS server, consider putting it in maintenance mode.

When FAS is in maintenance mode, the following holds true:

• When Workspace or StoreFront call FAS as part of the published application or desktop launch sequence, FAS indicates that it is in maintenance mode; the caller must react to this by choosing a different FAS server.
• As an extra precaution, FAS does not allow automatic creation of user certificates when in maintenance mode. Thus inadvertent creation of user certificates with unintended settings is avoided.
• However, activities involving existing user certificates, such as VDA sign-in or in-session usage, are still permitted.

Although automatic user certificate creation is not allowed, administrators can still create user certificates using PowerShell commands such as New-FasUserCertificate or Test-FasCertificateSigningRequest.

Using the administration console

Using PowerShell

Place a FAS server into maintenance mode as follows:

Set-FasServer -Address localhost -MaintenanceMode $true

Take a FAS server out of maintenance mode (and back into normal operation) as follows:

Set-FasServer -Address localhost -MaintenanceMode $false

Related information

• Install and configure is the primary reference for FAS installation and configuration.
• The common FAS deployments are summarized in the Federated Authentication Services architectures overview article.
• Other how-to articles are introduced in the Advanced configuration article.