Supported algorithms

This page describes the supported cryptographic algorithms.

Basics

There are multiple possibilities to configure the signing algorithm to use. We support both a symmetric key algorithm (HMAC), and two asymmetric key algorithms (RSA and ECDsa).

You configure it by:

• For signing: Assign a SignatureAlgorithm instance to the SigningSettings.
• For verification: Assign a SignatureAlgorithm instance to the Client instance.

Symmetric key

We support HMAC as symmetric cryptographic algorithm. Client and server share the secret of the client. This is the easiest set-up, but it comes with a greater security risk, because multiple parties know about the secret.

For signing

public static void ConfigureServices(IServiceCollection services) {
    services
        ...
        .AddHttpMessageSigning()
        .UseKeyId(KeyId)
        .UseSignatureAlgorithm(SignatureAlgorithm.CreateForSigning(Secret, HashAlgorithmName.SHA512));
}

Several overloads of the SignatureAlgorithm.CreateForSigning method are available. Use the one that suits you best.

You can also just "new up" a SignatureAlgorithm, if you prefer:

var signatureAlgorithm = new HMACSignatureAlgorithm("yumACY64r%hm", HashAlgorithmName.SHA512);

For verification

public static void ConfigureServices(IServiceCollection services) {
    services
        ...
        .AddHttpMessageSignatureVerification()
        .UseClient(
            Client.Create(
                new KeyId("e0e8dcd638334c409e1b88daf821d135"),
                "Sample client",
                SignatureAlgorithm.CreateForVerification(hmacSecret: "yumACY64r%hm"))
        );
}

Several overloads of the Client.Create method are available. Use the one that suits your needs best.

You can also just "new up" a SignatureAlgorithm, if you prefer:

var signatureAlgorithm = new HMACSignatureAlgorithm("yumACY64r%hm", HashAlgorithmName.SHA512);

Asymmetric key

If you do not want to share your private symmetric key between client and server, you can use the RSA or ECDsa asymmetric cryptographic algorithms. The code samples use the RSA option, but the usage of ECDsa is similar.

The advantage of this approach is that the server only needs to know the public key of the client. The client is the only party that knows about the private key, so that should eliminate the shared key attack vector.

For signing

public static void ConfigureServices(IServiceCollection services) {
    var cert = new X509Certificate2(File.ReadAllBytes("./dalion.local.pfx"), "CertP@ss123", X509KeyStorageFlags.Exportable);
    
    services
        ...
        .AddHttpMessageSigning()
        .UseKeyId(KeyId)
        .UseSignatureAlgorithm(SignatureAlgorithm.CreateForSigning(cert));
}

Several overloads of the SignatureAlgorithm.CreateForSigning method are available. Use the one that suits you best.

You can also just "new up" a SignatureAlgorithm, if you prefer:

var cert = new X509Certificate2(File.ReadAllBytes("./dalion.local.pfx"), "CertP@ss123", X509KeyStorageFlags.Exportable);
var signatureAlgorithmForSigning = new RSASignatureAlgorithm(HashAlgorithmName.SHA256, (RSACryptoServiceProvider)cert.PrivateKey);

Or something like...

var pem = ...;
var ecdsa = ECDsa.Create();
var derArray = Convert.FromBase64String(pem);
ecdsa.ImportPkcs8PrivateKey(derArray, out _);
var signatureAlgorithmForSigning = new ECDsaSignatureAlgorithm(HashAlgorithmName.SHA256, ecdsa);

For verification

public static void ConfigureServices(IServiceCollection services) {
    var cert = new X509Certificate2(File.ReadAllBytes("./dalion.local.pfx"), "CertP@ss123", X509KeyStorageFlags.Exportable);
    
    services
        ...
        .AddHttpMessageSignatureVerification()
        .UseClient(
            Client.Create(
                new KeyId("e0e8dcd638334c409e1b88daf821d135"),
                "Sample client",
                SignatureAlgorithm.CreateForVerification(cert))
        );
}

Several overloads of the Client.Create method are available. Use the one that suits your needs best.

You can also just "new up" a SignatureAlgorithm, if you prefer:

var cert = new X509Certificate2(File.ReadAllBytes("./dalion.local.pfx"), "CertP@ss123", X509KeyStorageFlags.Exportable);
var signatureAlgorithmForVerification = new RSASignatureAlgorithm(HashAlgorithmName.SHA256, (RSACryptoServiceProvider)cert.PublicKey.Key);

Or something like...

var pem = ...;
var ecdsa = ECDsa.Create();
var derArray = Convert.FromBase64String(pem);
ecdsa.ImportSubjectPublicKeyInfo(derArray, out _);
var signatureAlgorithmForVerification = new ECDsaSignatureAlgorithm(HashAlgorithmName.SHA256, ecdsa);

Supported hash algorithms

A signature algorithm also specifies the hash algorithm used to compute a hash value of the signature. Currently, the following algorithms are supported:

• MD5
• SHA1
• SHA256
• SHA384
• SHA512

Possible extensions

• Client self-registration by RSA public key exchange or Diffie-Hellman key exchange.
• ...