[API Proposal]: Additional span overloads for asymmetric signing and encryption

[vcsjones]

Background and motivation

For asymmetric signing (ECDsa, RSA) we have Sign APIs that accept a byte[] and TrySign APIs that accept a ReadOnlySpan<byte>.

There is not:

• Sign with an allocating return that accepts a ReadOnlySpan<byte>
• Sign with a write-to-destination that accepts a ReadOnlySpan<byte> and throws if the destination is too small.
• For RSA, similarly for encryption.

I propose we fill those API gaps.

API Proposal

namespace System.Security.Cryptography {
    public abstract partial class RSA {
        public byte[] Encrypt(
            ReadOnlySpan<byte> data,
            RSAEncryptionPadding padding);

        public int Encrypt(
            ReadOnlySpan<byte> data,
            Span<byte> destination,
            RSAEncryptionPadding padding);

        public byte[] Decrypt(
            ReadOnlySpan<byte> data,
            RSAEncryptionPadding padding);

        public int Decrypt(
            ReadOnlySpan<byte> data,
            Span<byte> destination,
            RSAEncryptionPadding padding);

        public byte[] SignData(
            ReadOnlySpan<byte> data,
            HashAlgorithmName hashAlgorithm,
            RSASignaturePadding padding);

        public int SignData(
            ReadOnlySpan<byte> data,
            Span<byte> destination,
            HashAlgorithmName hashAlgorithm,
            RSASignaturePadding padding);

        public byte[] SignHash(
            ReadOnlySpan<byte> hash,
            HashAlgorithmName hashAlgorithm,
            RSASignaturePadding padding);

        public int SignHash(
            ReadOnlySpan<byte> hash,
            Span<byte> destination,
            HashAlgorithmName hashAlgorithm,
            RSASignaturePadding padding);
    }

    public abstract partial class ECDsa {
        public byte[] SignData(
            ReadOnlySpan<byte> data,
            HashAlgorithmName hashAlgorithm,
            DSASignatureFormat signatureFormat);

        public byte[] SignData(
            ReadOnlySpan<byte> data,
            HashAlgorithmName hashAlgorithm);
            
        public int SignData(
            ReadOnlySpan<byte> data,
            Span<byte> destination,
            HashAlgorithmName hashAlgorithm,
            DSASignatureFormat signatureFormat);

        public int SignData(
            ReadOnlySpan<byte> data,
            Span<byte> destination,
            HashAlgorithmName hashAlgorithm);

        public byte[] SignHash(
            ReadOnlySpan<byte> hash,
            DSASignatureFormat signatureFormat);

        public byte[] SignHash(
            ReadOnlySpan<byte> hash);
            
        public int SignHash(
            ReadOnlySpan<byte> hash,
            Span<byte> destination,
            DSASignatureFormat signatureFormat);

        public int SignHash(
            ReadOnlySpan<byte> hash,
            Span<byte> destination);
    }
}

API Usage

Usage should be fairly straightforward.

Span<byte> hash = stackalloc byte[SHA256.HashSizeInBytes];
// Populate hash

byte[] signature = rsa.SignHash(hash, HashAlgorithmName.SHA256, RSASignaturePadding.Pss);

Alternative Designs

Do nothing. There are "Try*" APIs that can perform the operations on span, so these APIs don't enable new scenarios, but rather make typical scenarios less cumbersome. This also makes the available overloads more consistence with "the typical four".

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-security, @vcsjones
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

For asymmetric signing (ECDsa, RSA) we have Sign APIs that accept a byte[] and TrySign APIs that accept a ReadOnlySpan<byte>.

There is not:

• Sign with an allocating return that accepts a ReadOnlySpan<byte>
• Sign with a write-to-destination that accepts a ReadOnlySpan<byte> and throws if the destination is too small.
• For RSA, similarly for encryption.

I propose we fill those API gaps.

API Proposal

namespace System.Security.Cryptography {
    public abstract partial class RSA {
        public byte[] Encrypt(
            ReadOnlySpan<byte> data,
            RSAEncryptionPadding padding);

        public int Encrypt(
            ReadOnlySpan<byte> data,
            Span<byte> destination,
            RSAEncryptionPadding padding);

        public byte[] Decrypt(
            ReadOnlySpan<byte> data,
            RSAEncryptionPadding padding);

        public int Decrypt(
            ReadOnlySpan<byte> data,
            Span<byte> destination,
            RSAEncryptionPadding padding);

        public byte[] SignData(
            ReadOnlySpan<byte> data,
            HashAlgorithmName hashAlgorithm,
            RSASignaturePadding padding);

        public int SignData(
            ReadOnlySpan<byte> data,
            Span<byte> destination,
            HashAlgorithmName hashAlgorithm,
            RSASignaturePadding padding);

        public byte[] SignHash(
            ReadOnlySpan<byte> hash,
            HashAlgorithmName hashAlgorithm,
            RSASignaturePadding padding);

        public int SignHash(
            ReadOnlySpan<byte> hash,
            Span<byte> destination,
            HashAlgorithmName hashAlgorithm,
            RSASignaturePadding padding);
    }

    public abstract partial class ECDsa {
        public byte[] SignData(
            ReadOnlySpan<byte> data,
            HashAlgorithmName hashAlgorithm,
            DSASignatureFormat signatureFormat);

        public byte[] SignData(
            ReadOnlySpan<byte> data,
            HashAlgorithmName hashAlgorithm);
            
        public int SignData(
            ReadOnlySpan<byte> data,
            Span<byte> destination,
            HashAlgorithmName hashAlgorithm,
            DSASignatureFormat signatureFormat);

        public int SignData(
            ReadOnlySpan<byte> data,
            Span<byte> destination,
            HashAlgorithmName hashAlgorithm);

        public byte[] SignHash(
            ReadOnlySpan<byte> hash,
            DSASignatureFormat signatureFormat);

        public byte[] SignHash(
            ReadOnlySpan<byte> hash);
            
        public int SignHash(
            ReadOnlySpan<byte> hash,
            Span<byte> destination,
            DSASignatureFormat signatureFormat);

        public int SignHash(
            ReadOnlySpan<byte> hash,
            Span<byte> destination);
    }
}

API Usage

Usage should be fairly straightforward.

Span<byte> hash = stackalloc byte[SHA256.HashSizeInBytes];
// Populate hash

byte[] signature = rsa.SignHash(hash, HashAlgorithmName.SHA256, RSASignaturePadding.Pss);

Alternative Designs

Do nothing. There are "Try*" APIs that can perform the operations on span, so these APIs don't enable new scenarios, but rather make typical scenarios less cumbersome.

Risks

No response

Author:	vcsjones
Assignees:	-
Labels:	api-suggestion, area-System.Security
Milestone:	-

[bartonjs]

Looks good to me. There are a good number of Debug.Fail/unreachable blocks that can be deleted with the int-returning-Span-writing variant.

[terrajobst]

Video

• Looks good as proposed

namespace System.Security.Cryptography;

public abstract partial class RSA
{
    public byte[] Encrypt(
        ReadOnlySpan<byte> data,
        RSAEncryptionPadding padding);

    public int Encrypt(
        ReadOnlySpan<byte> data,
        Span<byte> destination,
        RSAEncryptionPadding padding);

    public byte[] Decrypt(
        ReadOnlySpan<byte> data,
        RSAEncryptionPadding padding);

    public int Decrypt(
        ReadOnlySpan<byte> data,
        Span<byte> destination,
        RSAEncryptionPadding padding);

    public byte[] SignData(
        ReadOnlySpan<byte> data,
        HashAlgorithmName hashAlgorithm,
        RSASignaturePadding padding);

    public int SignData(
        ReadOnlySpan<byte> data,
        Span<byte> destination,
        HashAlgorithmName hashAlgorithm,
        RSASignaturePadding padding);

    public byte[] SignHash(
        ReadOnlySpan<byte> hash,
        HashAlgorithmName hashAlgorithm,
        RSASignaturePadding padding);

    public int SignHash(
        ReadOnlySpan<byte> hash,
        Span<byte> destination,
        HashAlgorithmName hashAlgorithm,
        RSASignaturePadding padding);
}

public abstract partial class ECDsa
{
    public byte[] SignData(
        ReadOnlySpan<byte> data,
        HashAlgorithmName hashAlgorithm,
        DSASignatureFormat signatureFormat);

    public byte[] SignData(
        ReadOnlySpan<byte> data,
        HashAlgorithmName hashAlgorithm);
        
    public int SignData(
        ReadOnlySpan<byte> data,
        Span<byte> destination,
        HashAlgorithmName hashAlgorithm,
        DSASignatureFormat signatureFormat);

    public int SignData(
        ReadOnlySpan<byte> data,
        Span<byte> destination,
        HashAlgorithmName hashAlgorithm);

    public byte[] SignHash(
        ReadOnlySpan<byte> hash,
        DSASignatureFormat signatureFormat);

    public byte[] SignHash(
        ReadOnlySpan<byte> hash);
        
    public int SignHash(
        ReadOnlySpan<byte> hash,
        Span<byte> destination,
        DSASignatureFormat signatureFormat);

    public int SignHash(
        ReadOnlySpan<byte> hash,
        Span<byte> destination);
}