Public functions for validating keys

[ilammy]

The master branch currently contains new (semi-private) API for key validation and inspection:

• themis_is_valid_asym_key
• themis_get_asym_key_kind

It may be useful across the language wrappers so it should be exported in a consistent way, probably with specific implementations for validating keys for Secure Messages, Secure Session, etc.

[vixentael]

@ilammy would you mind to comment here if some language wrappers have these updates already? maybe Rust?

[ilammy]

Yeah, only Rust wrapper makes a good use of the exported API (duh...)
Some other wrappers have it technically available, but it's not really ready for use.

Overall availability status:

Language	Status
C core	✅ Available, but undocumented
Java	🚫 Not available
Swift, Objective-C	🚫 Not available
Python	❓ Private API for checking key kinds
PHP	🚫 Not available
Ruby	❓ Undocumented API for checking key kinds
C++	❓ Undocumented API for checking key kinds
Go	🚫 Not available
Node.js	🚫 Not available
Rust	✅ Available

As for particular languages and provided API...

C core

• Exported by <themis/secure_keygen.h> (has API comments)
• Check whether a buffer contains a valid asymmetric key: themis_is_valid_asym_key
• Query the kind of a key in the buffer: themis_get_asym_key_kind
• Key kind enumeration: themis_key_kind_t

Python

• Exported by smessage (privately)
• Check whether a byte array contains valid private or public key: _private_key, _public_key
• Key kind enumeration: THEMIS_KEY

Ruby

• Exported by Themis module (but not documented)
• Check whether a byte array contains a valid asymmetric key: valid_key
• Check whether a byte array contains valid private or public key: private_key, public_key
• Note that names break Ruby convention for predicates

C++

• Exported by <themispp/secure_keygen.hpp> (but not documented), in themispp namespace
• Check whether a byte array contains a valid asymmetric key: validate_key, is_valid_key
• Check whether a byte array contains valid private or public key: is_private_key, is_public_key
• Technically has access to C API as well

Rust

• Indirectly exported by themis::keys module, fully documented
• Provides strong types to differentiate between keys
• Check key kind and validity during construction: EcdsaPrivateKey::try_from_slice et al.
• Query key kind on generic types: PrivateKey::kind et al.
• Key kind enumeration: KeyKind

[ilammy]

I recall that strong key types is one of the desired features across all wrappers. Thus it seems to me that the best way to provide this API would be to integrate it with those new type constructors, like it's done in Rust. Then the users would be forced to validate the keys and ensure that they have correct kinds before passing them to Themis. We could also provide freestanding validation functions (like existing is_private ones), but I somewhat doubt their usefulness.

[vixentael]

I have a feeling that we've done here a lot, but no further public updates are planned, so I close this issue.