Share via

How to: Change the Cryptographic Provider for an X.509 Certificate's Private Key

  • Article

This topic shows how to change the cryptographic provider used to provide an X.509 certificate's private key and how to integrate the provider into the Windows Communication Foundation (WCF) security framework. For more information about using certificates, see Working with Certificates.

The WCF security framework provides a way to introduce new security token types as described in How to: Create a Custom Token. It is also possible to use a custom token to replace existing system-provided token types.

In this topic, the system-provided X.509 security token is replaced by a custom X.509 token that provides a different implementation for the certificate private key. This is useful in scenarios where the actual private key is provided by a different cryptographic provider than the default Windows cryptographic provider. One example of an alternative cryptographic provider is a hardware security module that performs all private key related cryptographic operations, and does not store the private keys in memory, thus improving security of the system.

The following example is for demonstration purposes only. It does not replace the default Windows cryptographic provider, but it shows where such a provider could be integrated.

Procedures

Every security token that has an associated security key or keys must implement the SecurityKeys property, which returns a collection of keys from the security token instance. If the token is an X.509 security token, the collection contains a single instance of the X509AsymmetricSecurityKey class that represents both public and private keys associated with the certificate. To replace the default cryptographic provider used to provide the certificate's keys, create a new implementation of this class.

To create a custom X.509 asymmetric key

  1. Define a new class derived from the X509AsymmetricSecurityKey class.

  2. Override the KeySize read-only property. This property returns the actual key size of the certificate's public/private key pair.

  3. Override the DecryptKey method. This method is called by the WCF security framework to decrypt a symmetric key with the certificate's private key. (The key was previously encrypted with the certificate's public key.)

  4. Override the GetAsymmetricAlgorithm method. This method is called by the WCF security framework to obtain an instance of the AsymmetricAlgorithm class that represents the cryptographic provider for either the certificate's private or public key, depending on the parameters passed to the method.

  5. Optional. Override the GetHashAlgorithmForSignature method. Override this method if a different implementation of the HashAlgorithm class is required.

  6. Override the GetSignatureFormatter method. This method returns an instance of the AsymmetricSignatureFormatter class that is associated with the certificate's private key.

  7. Override the IsSupportedAlgorithm method. This method is used to indicate whether a particular cryptographic algorithm is supported by the security key implementation.

    class CustomX509AsymmetricSecurityKey : X509AsymmetricSecurityKey
{
    X509Certificate2 certificate;
    object thisLock = new Object();
    bool privateKeyAvailabilityDetermined;
    AsymmetricAlgorithm privateKey;
    PublicKey publicKey;

    public CustomX509AsymmetricSecurityKey(X509Certificate2 certificate)
        : base(certificate)
    {
        this.certificate = certificate;
    }

    public override int KeySize
    {
        get { return this.PublicKey.Key.KeySize; }
    }

    AsymmetricAlgorithm PrivateKey
    {
        // You need to modify this to obtain the private key using a different cryptographic
        // provider if you do not want to use the default provider.
        get
        {
            if (!this.privateKeyAvailabilityDetermined)
            {
                lock (ThisLock)
                {
                    if (!this.privateKeyAvailabilityDetermined)
                    {
                        this.privateKey = this.certificate.PrivateKey;
                        this.privateKeyAvailabilityDetermined = true;
                    }
                }
            }
            return this.privateKey;
        }
    }

    PublicKey PublicKey
    {
        get
        {
            if (this.publicKey == null)
            {
                lock (ThisLock)
                {
                    if (this.publicKey == null)
                    {
                        this.publicKey = this.certificate.PublicKey;
                    }
                }
            }
            return this.publicKey;
        }
    }

    Object ThisLock
    {
        get
        {
            return thisLock;
        }
    }

    public override byte[] DecryptKey(string algorithm, byte[] keyData)
    {
        // You can decrypt the key only if you have the private key in the certificate.
        if (this.PrivateKey == null)
        {
            throw new NotSupportedException("Missing private key");
        }

        RSA rsa = this.PrivateKey as RSA;
        if (rsa == null)
        {
            throw new NotSupportedException("Private key cannot be used with RSA algorithm");
        }

        // Support exchange keySpec, AT_EXCHANGE ?
        if (rsa.KeyExchangeAlgorithm == null)
        {
            throw new NotSupportedException("Private key does not support key exchange");
        }

        switch (algorithm)
        {
            case EncryptedXml.XmlEncRSA15Url:
                return EncryptedXml.DecryptKey(keyData, rsa, false);

            case EncryptedXml.XmlEncRSAOAEPUrl:
                return EncryptedXml.DecryptKey(keyData, rsa, true);

            default:
                throw new NotSupportedException(String.Format("Algorithm {0} is not supported", algorithm));
        }
    }

    public override AsymmetricAlgorithm GetAsymmetricAlgorithm(string algorithm, bool privateKey)
    {
        if (privateKey)
        {
            if (this.PrivateKey == null)
            {
                throw new NotSupportedException("Missing private key");
            }

            switch (algorithm)
            {
                case SignedXml.XmlDsigDSAUrl:
                    if ((this.PrivateKey as DSA) != null)
                    {
                        return (this.PrivateKey as DSA);
                    }
                    throw new NotSupportedException("Private key cannot be used with DSA");

                case SignedXml.XmlDsigRSASHA1Url:
                case EncryptedXml.XmlEncRSA15Url:
                case EncryptedXml.XmlEncRSAOAEPUrl:
                    if ((this.PrivateKey as RSA) != null)
                    {
                        return (this.PrivateKey as RSA);
                    }
                    throw new NotSupportedException("Private key cannot be used with RSA");
                default:
                    throw new NotSupportedException(String.Format("Algorithm {0} is not supported", algorithm));
            }
        }
        else
        {
            switch (algorithm)
            {
                case SignedXml.XmlDsigDSAUrl:
                    if ((this.PublicKey.Key as DSA) != null)
                    {
                        return (this.PublicKey.Key as DSA);
                    }
                    throw new NotSupportedException("Public key cannot be used with DSA");
                case SignedXml.XmlDsigRSASHA1Url:
                case EncryptedXml.XmlEncRSA15Url:
                case EncryptedXml.XmlEncRSAOAEPUrl:
                    if ((this.PublicKey.Key as RSA) != null)
                    {
                        return (this.PublicKey.Key as RSA);
                    }
                    throw new NotSupportedException("Public key cannot be used with RSA");
                default:
                    throw new NotSupportedException(String.Format("Algorithm {0} is not supported", algorithm));
            }
        }
    }

    public override HashAlgorithm GetHashAlgorithmForSignature(string algorithm)
    {
        if (!this.IsSupportedAlgorithm(algorithm))
        {
            throw new NotSupportedException(String.Format("Algorithm {0} is not supported", algorithm));
        }

        switch (algorithm)
        {
            case SignedXml.XmlDsigDSAUrl:
            case SignedXml.XmlDsigRSASHA1Url:
                return new SHA1Managed();
            default:
                throw new NotSupportedException(String.Format("Algorithm {0} is not supported", algorithm));
        }
    }

    public override AsymmetricSignatureFormatter GetSignatureFormatter(string algorithm)
    {
        // The signature can be created only if the private key is present.
        if (this.PrivateKey == null)
        {
            throw new NotSupportedException("Private key is missing");
        }

        // Only one of the two algorithms is supported, not both.
        //     XmlDsigDSAUrl = "http://www.w3.org/2000/09/xmldsig#dsa-sha1";
        //     XmlDsigRSASHA1Url = "http://www.w3.org/2000/09/xmldsig#rsa-sha1";
        switch (algorithm)
        {
            case SignedXml.XmlDsigDSAUrl:

                // Ensure that this is a DSA algorithm object.
                DSA dsa = (this.PrivateKey as DSA);
                if (dsa == null)
                {
                    throw new NotSupportedException("Private key cannot be used DSA");
                }

                return new DSASignatureFormatter(dsa);

            case SignedXml.XmlDsigRSASHA1Url:
                // Ensure that this is an RSA algorithm object.
                RSA rsa = (this.PrivateKey as RSA);
                if (rsa == null)
                {
                    throw new NotSupportedException("Private key cannot be used RSA");
                }

                return new RSAPKCS1SignatureFormatter(rsa);
            default:
                throw new NotSupportedException(String.Format("Algorithm {0} is not supported", algorithm));
        }
    }

    public override bool IsSupportedAlgorithm(string algorithm)
    {
        switch (algorithm)
        {
            case SignedXml.XmlDsigDSAUrl:
                return (this.PublicKey.Key is DSA);

            case SignedXml.XmlDsigRSASHA1Url:
            case EncryptedXml.XmlEncRSA15Url:
            case EncryptedXml.XmlEncRSAOAEPUrl:
                return (this.PublicKey.Key is RSA);

            default:
                return false;
        }
    }
}

The following procedure shows how to integrate the custom X.509 asymmetric security key implementation created in the preceding procedure with the WCF security framework in order to replace the system-provided X.509 security token.

To replace the system-provided X.509 security token with a custom X.509 asymmetric security key token

  1. Create a custom X.509 security token that returns the custom X.509 asymmetric security key instead of the system-provided security key, as shown in the following example. For more information about custom security tokens, see How to: Create a Custom Token.

    class CustomX509SecurityToken : X509SecurityToken
{
    ReadOnlyCollection<SecurityKey> securityKeys;
    public CustomX509SecurityToken(X509Certificate2 certificate)
        : base(certificate)
    {
    }

    public override ReadOnlyCollection<SecurityKey> SecurityKeys
    {
        get
        {
            if (this.securityKeys == null)
            {
                List<SecurityKey> temp = new List<SecurityKey>(1);
                temp.Add(new CustomX509AsymmetricSecurityKey(this.Certificate));
                this.securityKeys = temp.AsReadOnly();
            }
            return this.securityKeys;
        }
    }
}

  2. Create a custom security token provider that returns a custom X.509 security token, as shown in the example. For more information about custom security token providers, see How to: Create a Custom Security Token Provider.

    class CustomX509SecurityTokenProvider : SecurityTokenProvider
{
    X509Certificate2 certificate;

    public CustomX509SecurityTokenProvider(X509Certificate2 certificate)
    {
        this.certificate = certificate;
    }

    protected override SecurityToken GetTokenCore(TimeSpan timeout)
    {
        return new CustomX509SecurityToken(certificate);
    }
}

  3. If the custom security key needs to be used on the initiator side, create a custom client security token manager and custom client credentials classes, as shown in the following example. For more information about custom client credentials and client security token managers, see How to: Create Custom Client and Service Credentials.

    class CustomClientSecurityTokenManager : ClientCredentialsSecurityTokenManager
{
    CustomClientCredentials credentials;

    public CustomClientSecurityTokenManager(CustomClientCredentials credentials)
        : base(credentials)
    {
        this.credentials = credentials;
    }

    public override SecurityTokenProvider CreateSecurityTokenProvider(SecurityTokenRequirement tokenRequirement)
    {
        SecurityTokenProvider result = null;

        if (tokenRequirement.TokenType == SecurityTokenTypes.X509Certificate)
        {
            MessageDirection direction = tokenRequirement.GetProperty<MessageDirection>(ServiceModelSecurityTokenRequirement.MessageDirectionProperty);
            if (direction == MessageDirection.Output)
            {
                if (tokenRequirement.KeyUsage == SecurityKeyUsage.Signature)
                {
                    result = new CustomX509SecurityTokenProvider(credentials.ClientCertificate.Certificate);
                }
            }
            else
            {
                if (tokenRequirement.KeyUsage == SecurityKeyUsage.Exchange)
                {
                    result = new CustomX509SecurityTokenProvider(credentials.ClientCertificate.Certificate);
                }
            }
        }

        if (result == null)
        {
            result = base.CreateSecurityTokenProvider(tokenRequirement);
        }
        return result;
    }
}

    public class CustomClientCredentials : ClientCredentials
{
    public CustomClientCredentials()
    {
    }

    protected CustomClientCredentials(CustomClientCredentials other)
        : base(other)
    {
    }

    protected override ClientCredentials CloneCore()
    {
        return new CustomClientCredentials(this);
    }

    public override SecurityTokenManager CreateSecurityTokenManager()
    {
        return new CustomClientSecurityTokenManager(this);
    }
}

  4. If the custom security key needs to be used on the recipient side, create a custom service security token manager and custom service credentials, as shown in the following example. For more information about custom service credentials and service security token managers, see How to: Create Custom Client and Service Credentials.

    class CustomServiceSecurityTokenManager : ServiceCredentialsSecurityTokenManager
{
    CustomServiceCredentials credentials;

    public CustomServiceSecurityTokenManager(CustomServiceCredentials credentials)
        : base(credentials)
    {
        this.credentials = credentials;
    }

    public override SecurityTokenProvider CreateSecurityTokenProvider(SecurityTokenRequirement tokenRequirement)
    {
        SecurityTokenProvider result = null;

        if (tokenRequirement.TokenType == SecurityTokenTypes.X509Certificate)
        {
            MessageDirection direction = tokenRequirement.GetProperty<MessageDirection>(ServiceModelSecurityTokenRequirement.MessageDirectionProperty);
            if (direction == MessageDirection.Input)
            {
                if (tokenRequirement.KeyUsage == SecurityKeyUsage.Exchange)
                {
                    result = new CustomX509SecurityTokenProvider(credentials.ServiceCertificate.Certificate);
                }
            }
            else
            {
                if (tokenRequirement.KeyUsage == SecurityKeyUsage.Signature)
                {
                    result = new CustomX509SecurityTokenProvider(credentials.ServiceCertificate.Certificate);
                }
            }
        }

        if (result == null)
        {
            result = base.CreateSecurityTokenProvider(tokenRequirement);
        }
        return result;
    }
}

    public class CustomServiceCredentials : ServiceCredentials
{
    public CustomServiceCredentials()
    {
    }

    protected CustomServiceCredentials(CustomServiceCredentials other)
        : base(other)
    {
    }

    protected override ServiceCredentials CloneCore()
    {
        return new CustomServiceCredentials(this);
    }

    public override SecurityTokenManager CreateSecurityTokenManager()
    {
        return new CustomServiceSecurityTokenManager(this);
    }
}

See Also

Tasks

How to: Create a Custom Security Token Provider

Reference

X509AsymmetricSecurityKey
AsymmetricSecurityKey
SecurityKey
AsymmetricAlgorithm
HashAlgorithm
AsymmetricSignatureFormatter

Concepts

How to: Create Custom Client and Service Credentials
How to: Create a Custom Security Token Authenticator
How to: Create a Custom Token
Security Architecture