Clarify the int param getter documentation

[mattcaswell]

OSSL_PARAMs that are of type OSSL_PARAM_INTEGER or
OSSL_PARAM_UNSIGNED_INTEGER can be obtained using any of the functions
EVP_PKEY_get_int_param(), EVP_PKEY_get_size_t_param() or
EVP_PKEY_get_bn_param(). The former two will fail if the parameter is too
large to fit into the C variable. We clarify this in the documentation.

[mouse07410]

Nice, thanks!

Is there a way to guide the reader to which of the functions he should use to retrieve the param value?

I.e., is it always recommended to use EVP_PKEY_get_bn_param() if it's of "arbitrary length"? Or is there a function that would tell the size? Or should one try _get_int_param(), if it fails - proceed to _get_size_t_param(), and finally progress to _get_bn_param()???

[paulidale]

Should this be in the notes section? It seems slightly out of place here. It's also more likely to be read if here.

[levitte]

Yeah, I would have this in NOTES

[mattcaswell]

I'd prefer to keep it here. As @paulidale says it is much more likely to be read here, and I think this is critical information for understanding how these functions work.

[t8m]

Nice, thanks!

Is there a way to guide the reader to which of the functions he should use to retrieve the param value?

I.e., is it always recommended to use EVP_PKEY_get_bn_param() if it's of "arbitrary length"? Or is there a function that would tell the size? Or should one try _get_int_param(), if it fails - proceed to _get_size_t_param(), and finally progress to _get_bn_param()???

It's IMO always - apply your reason about what the meaning of the parameter actually is. If it is some kind of length parameter get_size_t should be used. If it is some small integer parameter, you can use get_int_param. For the rest, use get_bn_param. Of course there are border-line cases such as the RSA e value which usually fits into int but can be an arbitrary big number. For this you could use the fallback approach but going right away with get_bn_param() would of course work as well.

[t8m]

I would be OK with keeping it here or moving it to NOTES, no problem with either choice.

[paulidale]

If you have the param, you can inspect the size directly. It is a public structure.

[mattcaswell]

Fixup pushed addressing the typo

[mattcaswell]

It's IMO always - apply your reason about what the meaning of the parameter actually is. If it is some kind of length parameter get_size_t should be used. If it is some small integer parameter, you can use get_int_param. For the rest, use get_bn_param. Of course there are border-line cases such as the RSA e value which usually fits into int but can be an arbitrary big number. For this you could use the fallback approach but going right away with get_bn_param() would of course work as well.

Can we indicate this somehow in the documentation for each parameter (not in this PR)? The parameter documentation all has a standard form, e.g.

=item "p" (B<OSSL_PKEY_PARAM_EC_P>) <unsigned integer>

Could we change that to something like:

=item "p" (B<OSSL_PKEY_PARAM_EC_P>) <unsigned integer> (typically use a B<BIGNUM>)

or

=item "size" (B<OSSL_DIGEST_PARAM_SIZE>) <unsigned integer> (typically use a C B<size_t>)

[openssl-machine]

This pull request is ready to merge

[paulidale]

Merged to 3.0 and master.