[BCrypt] GetProperty and SetProperty Identifiers: Add BCRYPT_PUBLIC_KEY_LENGTH + Additional Refactors

[ibuprof3n]

Adding the BCRYPT_PUBLIC_KEY_LENGTH identifier, including some additional information for when it applies to ECC curves.

Correcting the string values for some of the KEM identifiers.

[samuel-lee-msft]

Good to call out that ECC is peculiar, might wordsmith to something like:

The size, in bits, of the public key. This data type is a DWORD.

This specific size returned varies according to the algorithm. For programmatic use, most callers should use the pcbResult output of a BCryptExportKey call.

For most algorithms the returned length corresponds to the bit-size of the serialized public key without any further encoding. For ECC the returned length corresponds to the bit-size of the field modulus (P-256 returns 256 even though the public key is represented by a pair of 256-bit coordinates).

[ibuprof3n]

Ahh yea this is a lot better ahaha

We generally want callers to use the pcbResult output of a BCryptExportKey call when in a program right? Would it be worth including a variation of this line at the top of the file instead? I'm not entirely sure how all of the identifiers are used, but a general callout towards the top of this page might be worthwhile if this is the expectation for a lot of the identifiers.

Also, since there's a callout for ECC, it might be helpful to include a callout for KEM since the encapsulation key length is a slightly different terminology than the public key length terminology other algorithms use. I was thinking of something like:

For KEM, the returned length corresponds to the bit-size of the encapsulation key.

[samuel-lee-msft]

I tend to think Encapsulation key is just a fancy name for public key (in the BCrypt API we call it BCRYPT_MLKEM_PUBLIC_BLOB), I don't think it needs to be called out.

The BCryptExportKey comment could apply to the BCRYPT_KEY_LENGTH. Not opposed to putting something like this in the description for that property too.

[ibuprof3n]

@microsoft-github-policy-service agree company="Microsoft"

[prmerger-automator]

@ibuprof3n : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

[prmerger-automator]

@ibuprof3n : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

[alvinashcraft]

I'm adding @GrantMeStrength to the PR too. I've been moved over to the Microsoft Foundry docs team, so he can assign another writer if needed. The changes look good to me though, as long as @samuel-lee-msft is happy with them.