[Feature Request / Contribution Proposal] Private algorithm in builder pattern

[quexten]

Currently, the HeaderBuilder has:

/// Set the algorithm.
#[must_use]
pub fn algorithm(mut self, alg: iana::Algorithm) -> Self {
    self.0.alg = Some(Algorithm::Assigned(alg));
    self
}

Cose allows Private Use values (integers less than -65536), for non standardized algorithms. This can be useful for adopting algorithms widely regarded as safe and in certain contexts superior to the existing options (for example, XChaCha20, which has not been adopted into an RFC, but provides a clear benefit w.r.t. the nonce size).

This currently has to be represented as:

let mut protected_header = coset::HeaderBuilder::new().build();
protected_header.alg = Some(coset::Algorithm::PrivateUse(XCHACHA20_POLY1305));

not allowing to make use of the builder pattern.

My proposal is to add another option to the builder, along the lines of:

/// Set the algorithm.
#[must_use]
pub fn private_algorithm(mut self, alg: i64) -> Self {
    self.0.alg = Some(Algorithm::PrivateUse(alg));
    self
}

Unless there are concerns with this approach, I'm happy to send a PR adding this.

[daviddrysdale]

Adding a new builder method sounds fine, but it would be nice if the resulting value was definitely valid (i.e. within the private range) – could we come up with a tweaked method that ensures that?

[quexten]

That sounds reasonable. What would be the failure path? Return a Result<Self, CoseError>, of which the error path would return Err(CosetError::UnexpectedItem("iana assigned algorithm", "private use algorithm"));? The builder seems to not make use of Result so far.

[daviddrysdale]

That sounds OK, but it might also be nice to stick with the general convention of having a try_.. prefix for fallible builder methods.

So I guess use of this will end up looking something like:

let hdr = coset::HeaderBuilder::new()
                       .try_private_algorithm(XCHACHA20_POLY1305)
                       .unwrap(/* safe: value is in private range */)
                       .build();