Add Cross-Platform Cryptography document

[qmuntal]

This document is a port of Cross-Platform Cryptography in .NET.

This guide aims to replace our FIPS User Guide by being more user-friendly and easier to maintain. It is also a nice visual summary of what each backend supports and what needs more work.

Preview: https://github.com/microsoft/go/blob/dev/qmuntal/cpdoc/eng/doc/CrossPlatformCryptography.md

For #1377.

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

Tip: If you use Visual Studio Code, you can request a review from Copilot before you push from the "Source Control" tab. Learn more

[dagood]

Is it worth being more exact? Are there more potential situations than this one example?

Suggested change

	The RSA key size is subject to the limitations of the underlying cryptographic library. For example, on Windows and when using SCOSSL, the key size should be multiple of 8.
	The RSA key size is subject to the limitations of the underlying cryptographic library:
	* On Windows or when using SCOSSL, the key size must be a multiple of 8 (in bits).

But now I wonder if this was intended to be saying something about algorithms implemented by SCOSSL vs. by the built-in OpenSSL provider...

[qmuntal]

I intentionally didn't want to enumerate a possible limitations, as can vary in time and are normally not part of the public documentation of the crypto libraries.

[dagood]

Ah, makes sense. I think the doc probably should state that variability pretty clearly, because otherwise it might be a bit confusing why more detail isn't provided. Also, it sounds like the user is meant to get a hint that they should avoid depending on exact details here.

[dagood]

Nice!

[dagood]

Seeing this again, it feels a bit barer than it needs to be... I think a link and merging the paragraph helps make the context clearer. (A few more tweaks for flow, too.)

Suggested change

	Cryptographic operations in Microsoft Go are delegated to the operating system (OS) libraries in some conditions.
	Go apps will fall back to native Go implementations if the OS libraries don't support the algorithm.
	Cryptographic operations in Microsoft Go are delegated to the operating system (OS) libraries in some conditions described.
	The high level conditions and the benefits of delegating cryptographic operations are described in the [Microsoft Go FIPS README](./Readme.md).
	At a fine-grained level, Go apps will fall back to the native Go implementation of an algorithm if the OS libraries don't support it.

[dagood]

Suggested change

	SCOSSL is expected to be used with the default built-in provider enable as a fallback (which is the case when using [Azure Linux 3](https://github.com/microsoft/AzureLinux)).
	SCOSSL is expected to be used with the default built-in provider enabled as a fallback (which is the case when using [Azure Linux 3](https://github.com/microsoft/AzureLinux)).

[dagood]

For some reason it seems odd to say a table uses a legend--they both use the same symbols, but the tables don't really "use" the legend directly, to me.

Suggested change

	The following table legend is used to indicate the level of support for each cryptographic algorithm:
	The following legend describes the symbols used in the tables to indicate the level of support for each cryptographic algorithm:

[dagood]

This is the only time the doc mentions "user", and I think without a title like "FIPS 140-2 User Guide", it might be misinterpreted to mean that the dev's program will require some input from their end users. (Which doesn't make sense vs. a correct interpretation, but seems worth clarifying.)

Maybe the right fix is to actually update the intro to mention that this is a user guide for cryptography in Microsoft Go, to make "user" contextualized throughout the whole doc. (So maybe this can wait until this doc fully takes the place of the user guide.)

[dagood]

Suggested change

	When an algorithm is not supported or the limitations are not met, Microsoft Go will fall back to the Go implementation.
	When an algorithm is not supported or the limitations are exceeded, Microsoft Go will fall back to the Go implementation.

[dagood]

(Applying this suggestion to more places.)

Suggested change

	For those operations that require random numbers, only the [rand.Reader](https://pkg.go.dev/crypto/rand#Reader) is supported.
	Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).

[dagood]

Suggested change

	For those operations that require random numbers, only the [rand.Reader](https://pkg.go.dev/crypto/rand#Reader) is supported.
	Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).

[dagood]

Suggested change

	For those operations that require random numbers, only the [rand.Reader](https://pkg.go.dev/crypto/rand#Reader) is supported.
	Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).

[dagood]

Applying this suggestion to other places and adding in a link since it's in a different section.

Suggested change

	<sup>1</sup>The supported hash algorithms are the same as the ones supported as standalone hash functions.
	<sup>1</sup>Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms).

[dagood]

Suggested change

	<sup>1</sup>The supported hash algorithms are the same as the ones supported as standalone hash functions.
	<sup>1</sup>Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms).