[API Proposal]: PemEncoding.WriteString

[vcsjones]

Background and motivation

For a reason I no longer recall, PemEncoding.Write returns char[]. I think nearly all of the time, folks that choose to use the allocating version (as apposed to TryWrite) want a string, not a char[]. That means

1. You end up wrapping nearly every single PemEncoding.Write(...) to be new string(PemEncoding.Write(...)).
2. Doing 1 means you pay the allocation twice for the PEM. Once for the char array, and once again for the string.
3. If you want to do it as one allocation and you only have a ReadOnlySpan<byte> of data, getting a ReadOnlySpan<T> into the callback of string.Create currently requires unsafe code, so this starts becoming a little more than trivial. So developers don't have an easy way to do just the allocation once.

When implementing the PEM exports, this pretty much meant every time I would have preferred to use Write meant I actually had to use TryWrite in combination with GetEncodedSize and string.Create.

API Proposal

Since we can't change the return type...

namespace System.Security.Cryptography {
    public static class PemEncoding {
        public static string WriteString(ReadOnlySpan<char> label, ReadOnlySpan<byte> data);
    }
}

API Usage

Using ExportCertificatePem as an example:

runtime/src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X509Certificates/X509Certificate2.cs

Lines 1156 to 1168 in cf35d12

	public string ExportCertificatePem()
	{
	int pemSize = PemEncoding.GetEncodedSize(PemLabels.X509Certificate.Length, RawDataMemory.Length);
	return string.Create(pemSize, this, static (destination, cert) => {
	if (!cert.TryExportCertificatePem(destination, out int charsWritten) ||
	charsWritten != destination.Length)
	{
	Debug.Fail("Pre-allocated buffer was not the correct size.");
	throw new CryptographicException();
	}
	});
	}

Would become:

public string ExportCertificatePem()
{
    return PemEncoding.WriteString(PemLabels.X509Certificate, RawDataMemory.Span);
}

Alternative Designs

No response

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 a reason I no longer recall, PemEncoding.Write returns char[]. I think nearly all of the time, folks that choose to use the allocating version (as apposed to TryWrite) want a string, not a char[]. That means

1. You end up wrapping nearly every single PemEncoding.Write(...) to be new string(PemEncoding.Write(...)).
2. Doing 1 means you pay the allocation twice for the PEM. Once for the char array, and once again for the string.
3. If you want to do it as one allocation and you only have a ReadOnlySpan<char> of data, getting a ReadOnlySpan<T> into the callback of string.Create currently requires unsafe code, so this starts becoming a little more than trivial. So developers don't have an easy way to do just the allocation once.

When implementing the PEM exports, this pretty much meant every time I would have preferred to use Write meant I actually had to use TryWrite in combination with GetEncodedSize and string.Create.

API Proposal

Since we can't change the return type...

namespace System.Security.Cryptography {
    public static class PemEncoding {
        public string WriteString(ReadOnlySpan<char> label, ReadOnlySpan<byte> data);
    }
}

API Usage

Using ExportCertificatePem as an example:

runtime/src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X509Certificates/X509Certificate2.cs

Lines 1156 to 1168 in cf35d12

	public string ExportCertificatePem()
	{
	int pemSize = PemEncoding.GetEncodedSize(PemLabels.X509Certificate.Length, RawDataMemory.Length);
	return string.Create(pemSize, this, static (destination, cert) => {
	if (!cert.TryExportCertificatePem(destination, out int charsWritten) ||
	charsWritten != destination.Length)
	{
	Debug.Fail("Pre-allocated buffer was not the correct size.");
	throw new CryptographicException();
	}
	});
	}

Would become:

public string ExportCertificatePem()
{
    return PemEncoding.WriteString(PemLabels.X509Certificate, RawDataMemory.Span);
}

Alternative Designs

No response

Risks

No response

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

[vcsjones]

Branch with implementation main...vcsjones:writestring-impl

[bartonjs]

Looks good as proposed

namespace System.Security.Cryptography {
    public static class PemEncoding {
        public static string WriteString(ReadOnlySpan<char> label, ReadOnlySpan<byte> data);
    }
}