Is there a standard way to mark some functions in a crate as 'for experts only'?

171 points XiPingTing

I am new to Rust but not to programming. I am writing a user-friendly post-quantum signature algorithm. The workhorse is FALCON, but I have chosen some defaults that make the interface as unscary as possible.

fn get_public_key(private_key: [u8;32]) -> [u8;32]

fn sign(private_key: [u8;32], secret_nonce: [u8;32]) -> [u8; 1563];
fn verify(public_key: [u8;32], signature: [u8; 1563]) -> bool;

Anyone who knows anything about FALCON would wince a little. The public keys are being concatenated into every signature. The user is being trusted to generate cryptographically secure random numbers. The security level is fixed and not at the highest level. SHAKE needs to be seeded, sometimes twice, any time someone tries to do anything. Public keys are being recalculated at great expense for every signature.

But it's stateless, deterministic, fixed length, allocation-free, friendly.

I therefore also want to expose an interface for experts, with options to reuse seeded random number generators, use ChaCha20 instead of SHAKE, point to a thread-local scratch pad, use the CPRNGs elsewhere, use larger lattices etc.

I am thinking of just prepending scary_ to all the public functions most people shouldn't use. Is there a better way?