Remove X509_STORE_CTX_purpose_inherit(3) documentation

This abomination of an API will be removed. Remove the hairy details of
its internals and make the documentation of X509_STORE_CTX_set_trust(3)
and X509_STORE_CTX_set_purpose(3) independent of it.

Neither of these two remaining APIs can be recommended. Once set, trust
and purpose are sticky. Setting the trust to a different (valid) value
will indicate success but leave the value unchanged. I suppose it means
the new trust value was successfully ignored. Also, setting the trust to
X509_TRUST_DEFAULT can succeed or fail depending on which OpenSSL
derivative you use. Setting the purpose will also set the trust (unless
it is already set). Setting some purposes may or may not fail depending
on the OpenSSL lib.

The only way you have a chance of knowing what will be set is by calling
only one of these functions directly after X509_STORE_CTX_init(). This
isn't really safe either because in some versions the user can override
the values stored in a global table by writing directly to it.

The actual contributions here are rather minimal. State more explicitly
that 0 is invalid (but results in success being returned), document the
error values to be accurate across implementations and call out some of
the nonsense in a CAVEATS section.

Many thanks to schwarze for the very helpful review with lots of input.

ok schwarze

0 files changed, 0 insertions, 0 deletions