use core::fmt;
use std::error::Error;
use std::str::FromStr;
use crate::fields::{FieldText, SignatureFieldError};
use crate::header::{HeaderError, HeaderName, Headers};
pub const SIGNATURE_INPUT_HEADER_NAME: &str = "Signature-Input";
pub const SIGNIFY_TIMESTAMP_HEADER_NAME: &str = "Signify-Timestamp";
pub const SIGNIFY_RESOURCE_HEADER_NAME: &str = "Signify-Resource";
pub const METHOD_COMPONENT: &str = "@method";
pub const PATH_COMPONENT: &str = "@path";
pub const SIGNATURE_PARAMS_COMPONENT: &str = "@signature-params";
pub const ED25519_ALGORITHM: &str = "ed25519";
pub const SIGNIFY_LABEL: &str = "signify";
pub const MAX_SIGNATURE_INPUT_BYTES: usize = 16 * 1024;
pub const MAX_SIGNATURE_BASE_BYTES: usize = 64 * 1024;
pub const MAX_LABEL_BYTES: usize = 64;
pub const MAX_COMPONENTS: usize = 64;
pub const MAX_INPUTS: usize = 16;
pub const MAX_REQUEST_PATH_BYTES: usize = 4096;
pub const MAX_REQUEST_METHOD_BYTES: usize = 64;
pub const MAX_PARAMETER_INTEGER: u64 = 999_999_999_999_999;
#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub struct InputLabel {
text: String,
}
impl InputLabel {
#[must_use]
pub fn signify() -> Self {
Self {
text: SIGNIFY_LABEL.to_owned(),
}
}
pub fn new(text: impl Into<String>) -> Result<Self, SignatureInputError> {
let text = text.into();
let invalid = || SignatureInputError::InvalidLabel { label: bounded(&text) };
if text.is_empty() || text.len() > MAX_LABEL_BYTES {
return Err(invalid());
}
let mut bytes = text.bytes();
match bytes.next() {
Some(byte) if byte.is_ascii_lowercase() || byte == b'*' => {}
_ => return Err(invalid()),
}
if !bytes.all(is_key_byte) {
return Err(invalid());
}
Ok(Self { text })
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.text
}
}
impl FromStr for InputLabel {
type Err = SignatureInputError;
fn from_str(input: &str) -> Result<Self, Self::Err> {
Self::new(input)
}
}
impl fmt::Display for InputLabel {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.text)
}
}
const fn is_key_byte(byte: u8) -> bool {
byte.is_ascii_lowercase() || byte.is_ascii_digit() || matches!(byte, b'_' | b'-' | b'.' | b'*')
}
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum SignatureComponent {
Method,
Path,
Header(HeaderName),
Unsupported(FieldText),
}
impl SignatureComponent {
pub fn new(name: &str) -> Result<Self, SignatureInputError> {
match name {
METHOD_COMPONENT => Ok(Self::Method),
PATH_COMPONENT => Ok(Self::Path),
_ if name.starts_with('@') => Err(SignatureInputError::UnknownDerivedComponent { name: bounded(name) }),
_ => Ok(Self::Header(HeaderName::new(name)?)),
}
}
#[must_use]
pub fn as_str(&self) -> &str {
match self {
Self::Method => METHOD_COMPONENT,
Self::Path => PATH_COMPONENT,
Self::Header(name) => name.as_str(),
Self::Unsupported(name) => name.as_str(),
}
}
fn is_same(&self, other: &Self) -> bool {
match (self, other) {
(Self::Method, Self::Method) | (Self::Path, Self::Path) => true,
(Self::Header(left), Self::Header(right)) => left == right,
(Self::Unsupported(left), Self::Unsupported(right)) => left == right,
_ => false,
}
}
}
impl FromStr for SignatureComponent {
type Err = SignatureInputError;
fn from_str(input: &str) -> Result<Self, Self::Err> {
Self::new(input)
}
}
impl fmt::Display for SignatureComponent {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(self.as_str())
}
}
pub fn default_components() -> Result<Vec<SignatureComponent>, SignatureInputError> {
Ok(vec![
SignatureComponent::Method,
SignatureComponent::Path,
SignatureComponent::Header(HeaderName::new(SIGNIFY_RESOURCE_HEADER_NAME.to_ascii_lowercase())?),
SignatureComponent::Header(HeaderName::new(SIGNIFY_TIMESTAMP_HEADER_NAME.to_ascii_lowercase())?),
])
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct RequestTarget {
method: String,
path: String,
}
impl RequestTarget {
pub fn new(method: &str, path: &str) -> Result<Self, SignatureInputError> {
if method.is_empty() || method.len() > MAX_REQUEST_METHOD_BYTES || !method.bytes().all(is_method_byte) {
return Err(SignatureInputError::InvalidRequestMethod {
method: bounded(method),
});
}
if path.is_empty()
|| path.len() > MAX_REQUEST_PATH_BYTES
|| !path.starts_with('/')
|| !path.bytes().all(is_path_byte)
{
return Err(SignatureInputError::InvalidRequestPath { path: bounded(path) });
}
Ok(Self {
method: method.to_owned(),
path: path.to_owned(),
})
}
#[must_use]
pub fn method(&self) -> &str {
&self.method
}
#[must_use]
pub fn path(&self) -> &str {
&self.path
}
}
const fn is_method_byte(byte: u8) -> bool {
byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b'*' | b'!' | b'~' | b'\'' | b'+' | b'`')
}
const fn is_path_byte(byte: u8) -> bool {
byte.is_ascii_graphic() && !matches!(byte, b'?' | b'#' | b'"')
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SignatureBase {
text: String,
}
impl SignatureBase {
#[must_use]
pub fn as_str(&self) -> &str {
&self.text
}
#[must_use]
pub fn as_bytes(&self) -> &[u8] {
self.text.as_bytes()
}
}
impl fmt::Display for SignatureBase {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.text)
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
enum Expires {
Time(u64),
Text(FieldText),
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SignatureInput {
label: InputLabel,
components: Vec<SignatureComponent>,
created: u64,
expires: Option<Expires>,
nonce: Option<FieldText>,
key_identifier: Option<FieldText>,
context: Option<FieldText>,
algorithm: Option<FieldText>,
}
impl SignatureInput {
#[must_use]
pub const fn label(&self) -> &InputLabel {
&self.label
}
#[must_use]
pub fn components(&self) -> &[SignatureComponent] {
&self.components
}
#[must_use]
pub const fn created(&self) -> u64 {
self.created
}
#[must_use]
pub const fn expires(&self) -> Option<u64> {
match self.expires {
Some(Expires::Time(expires)) => Some(expires),
Some(Expires::Text(_)) | None => None,
}
}
#[must_use]
pub fn nonce(&self) -> Option<&str> {
self.nonce.as_ref().map(FieldText::as_str)
}
#[must_use]
pub fn key_identifier(&self) -> Option<&str> {
self.key_identifier.as_ref().map(FieldText::as_str)
}
#[must_use]
pub fn context(&self) -> Option<&str> {
self.context.as_ref().map(FieldText::as_str)
}
#[must_use]
pub fn algorithm(&self) -> Option<&str> {
self.algorithm.as_ref().map(FieldText::as_str)
}
pub fn signature_base(
&self,
target: &RequestTarget,
headers: &Headers,
) -> Result<SignatureBase, SignatureInputError> {
if self.components.is_empty() {
return Err(SignatureInputError::NoComponents);
}
let mut items: Vec<String> = Vec::with_capacity(self.components.len().saturating_add(1));
for component in &self.components {
let value = match component {
SignatureComponent::Method => target.method(),
SignatureComponent::Path => target.path(),
SignatureComponent::Header(name) => {
headers
.get(name.as_str())
.ok_or_else(|| SignatureInputError::MissingCoveredHeader {
name: bounded(name.as_str()),
})?
}
SignatureComponent::Unsupported(name) => {
return Err(SignatureInputError::UnknownDerivedComponent {
name: bounded(name.as_str()),
});
}
};
items.push(format!("\"{}\": {value}", component.as_str()));
}
self.finish_base(items)
}
pub fn received_base(
&self,
target: &RequestTarget,
headers: &Headers,
) -> Result<SignatureBase, SignatureInputError> {
let mut items: Vec<String> = Vec::with_capacity(self.components.len().saturating_add(1));
for component in &self.components {
match component {
SignatureComponent::Method => items.push(format!("\"{METHOD_COMPONENT}\": {}", target.method())),
SignatureComponent::Path => items.push(format!("\"{PATH_COMPONENT}\": {}", target.path())),
SignatureComponent::Header(name) => {
if let Some(value) = headers.get(name.as_str()) {
items.push(format!("\"{}\": {}", name.as_str().to_ascii_lowercase(), value.trim()));
}
}
SignatureComponent::Unsupported(_) => {}
}
}
self.finish_base(items)
}
fn finish_base(&self, mut items: Vec<String>) -> Result<SignatureBase, SignatureInputError> {
items.push(format!(
"\"{SIGNATURE_PARAMS_COMPONENT}: {}\"",
self.render_parameters(false)
));
let text = items.join("\n");
if text.len() > MAX_SIGNATURE_BASE_BYTES {
return Err(SignatureInputError::SignatureBaseTooLong {
length: text.len(),
maximum: MAX_SIGNATURE_BASE_BYTES,
});
}
Ok(SignatureBase { text })
}
fn render_parameters(&self, quoted: bool) -> String {
let names = self
.components
.iter()
.map(|component| {
if quoted {
format!("\"{}\"", component.as_str())
} else {
component.as_str().to_owned()
}
})
.collect::<Vec<_>>()
.join(" ");
let mut rendered = format!("({names});created={}", self.created);
if let Some(Expires::Time(expires)) = &self.expires {
rendered.push_str(";expires=");
rendered.push_str(&expires.to_string());
}
let expires_text = match &self.expires {
Some(Expires::Text(text)) => Some(text),
_ => None,
};
for (name, value) in [
("expires", expires_text),
("nonce", self.nonce.as_ref()),
("keyid", self.key_identifier.as_ref()),
("context", self.context.as_ref()),
("alg", self.algorithm.as_ref()),
] {
let Some(value) = value else { continue };
rendered.push(';');
rendered.push_str(name);
rendered.push('=');
if quoted {
rendered.push('"');
rendered.push_str(value.as_str());
rendered.push('"');
} else {
rendered.push_str(value.as_str());
}
}
rendered
}
fn render(&self) -> String {
format!("{}={}", self.label, self.render_parameters(true))
}
}
#[derive(Clone, Debug)]
pub struct SignatureInputBuilder {
label: InputLabel,
components: Vec<SignatureComponent>,
created: u64,
expires: Option<Expires>,
nonce: Option<FieldText>,
key_identifier: Option<FieldText>,
context: Option<FieldText>,
algorithm: Option<FieldText>,
}
impl SignatureInputBuilder {
#[must_use]
pub const fn new(label: InputLabel, components: Vec<SignatureComponent>, created: u64) -> Self {
Self {
label,
components,
created,
expires: None,
nonce: None,
key_identifier: None,
context: None,
algorithm: None,
}
}
#[must_use]
pub fn expires(mut self, expires: u64) -> Self {
self.expires = Some(Expires::Time(expires));
self
}
#[must_use]
pub fn nonce(mut self, nonce: FieldText) -> Self {
self.nonce = Some(nonce);
self
}
#[must_use]
pub fn key_identifier(mut self, key_identifier: FieldText) -> Self {
self.key_identifier = Some(key_identifier);
self
}
#[must_use]
pub fn context(mut self, context: FieldText) -> Self {
self.context = Some(context);
self
}
#[must_use]
pub fn algorithm(mut self, algorithm: FieldText) -> Self {
self.algorithm = Some(algorithm);
self
}
pub fn build(self) -> Result<SignatureInput, SignatureInputError> {
if self.components.is_empty() {
return Err(SignatureInputError::NoComponents);
}
if self.components.len() > MAX_COMPONENTS {
return Err(SignatureInputError::TooManyComponents {
count: self.components.len(),
maximum: MAX_COMPONENTS,
});
}
if let Some(SignatureComponent::Unsupported(name)) = self
.components
.iter()
.find(|component| matches!(component, SignatureComponent::Unsupported(_)))
{
return Err(SignatureInputError::UnknownDerivedComponent {
name: bounded(name.as_str()),
});
}
for (position, component) in self.components.iter().enumerate() {
if self
.components
.iter()
.take(position)
.any(|earlier| earlier.is_same(component))
{
return Err(SignatureInputError::DuplicateComponent {
name: bounded(component.as_str()),
});
}
}
self.finish()
}
fn finish(self) -> Result<SignatureInput, SignatureInputError> {
let expires = match self.expires {
Some(Expires::Time(expires)) => Some(expires),
_ => None,
};
for (name, value) in [("created", Some(self.created)), ("expires", expires)] {
if value.is_some_and(|value| value > MAX_PARAMETER_INTEGER) {
return Err(SignatureInputError::ParameterOutOfRange { name });
}
}
for (name, value) in [
("nonce", self.nonce.as_ref()),
("keyid", self.key_identifier.as_ref()),
("context", self.context.as_ref()),
("alg", self.algorithm.as_ref()),
] {
if value.is_some_and(|value| value.as_str().contains('\\')) {
return Err(SignatureInputError::InvalidParameterValue { name });
}
}
Ok(SignatureInput {
label: self.label,
components: self.components,
created: self.created,
expires: self.expires,
nonce: self.nonce,
key_identifier: self.key_identifier,
context: self.context,
algorithm: self.algorithm,
})
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SignatureInputHeader {
inputs: Vec<SignatureInput>,
}
impl SignatureInputHeader {
pub const NAME: &'static str = SIGNATURE_INPUT_HEADER_NAME;
pub fn new(inputs: Vec<SignatureInput>) -> Result<Self, SignatureInputError> {
if inputs.is_empty() {
return Err(SignatureInputError::NoInputs);
}
if inputs.len() > MAX_INPUTS {
return Err(SignatureInputError::TooManyInputs {
count: inputs.len(),
maximum: MAX_INPUTS,
});
}
for (position, input) in inputs.iter().enumerate() {
if inputs
.iter()
.take(position)
.any(|earlier| earlier.label() == input.label())
{
return Err(SignatureInputError::DuplicateLabel {
label: bounded(input.label().as_str()),
});
}
}
Ok(Self { inputs })
}
#[must_use]
pub fn inputs(&self) -> &[SignatureInput] {
&self.inputs
}
#[must_use]
pub fn find(&self, label: &InputLabel) -> Option<&SignatureInput> {
self.inputs.iter().find(|input| input.label() == label)
}
pub fn to_header_value(&self) -> Result<String, SignatureInputError> {
let rendered = self
.inputs
.iter()
.map(SignatureInput::render)
.collect::<Vec<_>>()
.join(", ");
if rendered.len() > MAX_SIGNATURE_INPUT_BYTES {
return Err(SignatureInputError::SignatureInputTooLong {
length: rendered.len(),
maximum: MAX_SIGNATURE_INPUT_BYTES,
});
}
Ok(rendered)
}
pub fn parse(value: &str) -> Result<Self, SignatureInputError> {
Self::parse_with(value, false)
}
pub fn parse_received(value: &str) -> Result<Self, SignatureInputError> {
Self::parse_with(value, true)
}
fn parse_with(value: &str, received: bool) -> Result<Self, SignatureInputError> {
if value.len() > MAX_SIGNATURE_INPUT_BYTES {
return Err(SignatureInputError::SignatureInputTooLong {
length: value.len(),
maximum: MAX_SIGNATURE_INPUT_BYTES,
});
}
let mut parser = Parser::new(value, received);
let mut inputs = Vec::new();
loop {
inputs.push(parser.parse_input()?);
if !parser.eat(b',') {
break;
}
parser.skip_whitespace();
}
if !parser.is_finished() {
return Err(parser.malformed("trailing material"));
}
Self::new(inputs)
}
}
impl FromStr for SignatureInputHeader {
type Err = SignatureInputError;
fn from_str(input: &str) -> Result<Self, Self::Err> {
Self::parse(input)
}
}
impl TryFrom<&str> for SignatureInputHeader {
type Error = SignatureInputError;
fn try_from(input: &str) -> Result<Self, Self::Error> {
Self::parse(input)
}
}
const PARAMETER_ORDER: [&str; 6] = ["created", "expires", "nonce", "keyid", "context", "alg"];
struct Parser<'input> {
bytes: &'input [u8],
position: usize,
received: bool,
}
impl<'input> Parser<'input> {
const fn new(value: &'input str, received: bool) -> Self {
Self {
bytes: value.as_bytes(),
position: 0,
received,
}
}
fn peek(&self) -> Option<u8> {
self.bytes.get(self.position).copied()
}
fn eat(&mut self, byte: u8) -> bool {
if self.peek() == Some(byte) {
self.position = self.position.saturating_add(1);
return true;
}
false
}
fn skip_whitespace(&mut self) {
while matches!(self.peek(), Some(b' ' | b'\t')) {
self.position = self.position.saturating_add(1);
}
}
const fn is_finished(&self) -> bool {
self.position >= self.bytes.len()
}
fn malformed(&self, reason: &'static str) -> SignatureInputError {
SignatureInputError::Malformed {
reason,
offset: self.position,
}
}
fn take_while(&mut self, accept: fn(u8) -> bool) -> &'input str {
let start = self.position;
while self.peek().is_some_and(accept) {
self.position = self.position.saturating_add(1);
}
self.bytes
.get(start..self.position)
.and_then(|slice| core::str::from_utf8(slice).ok())
.unwrap_or_default()
}
fn parse_input(&mut self) -> Result<SignatureInput, SignatureInputError> {
let label = InputLabel::new(self.take_while(|byte| is_key_byte(byte) || byte == b'*'))?;
if !self.eat(b'=') {
return Err(self.malformed("a member needs a value"));
}
let components = self.parse_components()?;
let mut created = None;
let mut expires = None;
let mut nonce = None;
let mut key_identifier = None;
let mut context = None;
let mut algorithm = None;
let mut last_position: Option<usize> = None;
while self.eat(b';') {
let name = self.take_while(is_key_byte);
if name.is_empty() {
return Err(self.malformed("a parameter needs a name"));
}
let Some(order) = PARAMETER_ORDER.iter().position(|known| *known == name) else {
return Err(SignatureInputError::UnknownParameter { name: bounded(name) });
};
if last_position.is_some_and(|last| order <= last) {
return Err(SignatureInputError::ParametersOutOfOrder);
}
last_position = Some(order);
if !self.eat(b'=') {
return Err(self.malformed("a parameter needs a value"));
}
match name {
"created" => created = Some(self.parse_integer()?),
"expires" if self.received && self.peek() == Some(b'"') => {
expires = Some(Expires::Text(self.parse_text()?));
}
"expires" => expires = Some(Expires::Time(self.parse_integer()?)),
"nonce" => nonce = Some(self.parse_text()?),
"keyid" => key_identifier = Some(self.parse_text()?),
"context" => context = Some(self.parse_text()?),
_ => algorithm = Some(self.parse_text()?),
}
}
let created = created.ok_or(SignatureInputError::MissingCreated {
label: bounded(label.as_str()),
})?;
let mut builder = SignatureInputBuilder::new(label, components, created);
builder.expires = expires;
if let Some(nonce) = nonce {
builder = builder.nonce(nonce);
}
if let Some(key_identifier) = key_identifier {
builder = builder.key_identifier(key_identifier);
}
if let Some(context) = context {
builder = builder.context(context);
}
if let Some(algorithm) = algorithm {
builder = builder.algorithm(algorithm);
}
if self.received {
return builder.finish();
}
builder.build()
}
fn parse_components(&mut self) -> Result<Vec<SignatureComponent>, SignatureInputError> {
if !self.eat(b'(') {
return Err(self.malformed("a covered list must start with `(`"));
}
let mut components = Vec::new();
self.skip_whitespace();
loop {
if self.eat(b')') {
return Ok(components);
}
if components.len() >= MAX_COMPONENTS {
return Err(SignatureInputError::TooManyComponents {
count: components.len().saturating_add(1),
maximum: MAX_COMPONENTS,
});
}
let name = self.parse_quoted()?;
components.push(match SignatureComponent::new(name) {
Err(SignatureInputError::UnknownDerivedComponent { .. }) if self.received => {
SignatureComponent::Unsupported(FieldText::new(name)?)
}
component => component?,
});
match self.peek() {
Some(b' ' | b'\t') => self.skip_whitespace(),
Some(b')') => {}
_ => return Err(self.malformed("a covered list needs a space or `)` after a name")),
}
}
}
fn parse_quoted(&mut self) -> Result<&'input str, SignatureInputError> {
if !self.eat(b'"') {
return Err(self.malformed("a quoted string must start with `\"`"));
}
let text = self.take_while(|byte| matches!(byte, 0x20..=0x7e) && byte != b'"' && byte != b'\\');
if !self.eat(b'"') {
return Err(self.malformed("a quoted string is unterminated or holds an escape"));
}
Ok(text)
}
fn parse_text(&mut self) -> Result<FieldText, SignatureInputError> {
let text = self.parse_quoted()?;
Ok(FieldText::new(text)?)
}
fn parse_integer(&mut self) -> Result<u64, SignatureInputError> {
if self.peek() == Some(b'-') {
return Err(self.malformed("a time parameter may not be negative"));
}
let digits = self.take_while(|byte| byte.is_ascii_digit());
if digits.is_empty() {
return Err(self.malformed("a time parameter needs digits"));
}
if digits.len() > 1 && digits.starts_with('0') {
return Err(self.malformed("a time parameter may not carry a leading zero"));
}
digits
.parse::<u64>()
.ok()
.filter(|value| *value <= MAX_PARAMETER_INTEGER)
.ok_or(SignatureInputError::ParameterOutOfRange { name: "time" })
}
}
fn bounded(text: &str) -> String {
text.chars().take(32).collect()
}
#[derive(Debug)]
#[non_exhaustive]
pub enum SignatureInputError {
SignatureInputTooLong {
length: usize,
maximum: usize,
},
SignatureBaseTooLong {
length: usize,
maximum: usize,
},
InvalidLabel {
label: String,
},
UnknownDerivedComponent {
name: String,
},
InvalidRequestMethod {
method: String,
},
InvalidRequestPath {
path: String,
},
NoComponents,
TooManyComponents {
count: usize,
maximum: usize,
},
DuplicateComponent {
name: String,
},
MissingCoveredHeader {
name: String,
},
NoInputs,
TooManyInputs {
count: usize,
maximum: usize,
},
DuplicateLabel {
label: String,
},
MissingCreated {
label: String,
},
UnknownParameter {
name: String,
},
ParametersOutOfOrder,
ParameterOutOfRange {
name: &'static str,
},
InvalidParameterValue {
name: &'static str,
},
Malformed {
reason: &'static str,
offset: usize,
},
Header {
source: HeaderError,
},
Field {
source: SignatureFieldError,
},
}
impl From<HeaderError> for SignatureInputError {
fn from(source: HeaderError) -> Self {
Self::Header { source }
}
}
impl From<SignatureFieldError> for SignatureInputError {
fn from(source: SignatureFieldError) -> Self {
Self::Field { source }
}
}
impl fmt::Display for SignatureInputError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::SignatureInputTooLong { length, maximum } => {
write!(formatter, "signature input of {length} bytes exceeds maximum {maximum}")
}
Self::SignatureBaseTooLong { length, maximum } => {
write!(formatter, "signature base of {length} bytes exceeds maximum {maximum}")
}
Self::InvalidLabel { label } => {
write!(formatter, "signature input label {label:?} is not a dictionary key")
}
Self::UnknownDerivedComponent { name } => write!(
formatter,
"derived component {name:?} is not one of {METHOD_COMPONENT:?} or {PATH_COMPONENT:?}"
),
Self::InvalidRequestMethod { method } => {
write!(formatter, "request method {method:?} is not a token")
}
Self::InvalidRequestPath { path } => write!(
formatter,
"request path {path:?} must be absolute, query-free, and visible ASCII"
),
Self::NoComponents => formatter.write_str("a signature input covers nothing"),
Self::TooManyComponents { count, maximum } => {
write!(
formatter,
"a signature input covers {count} components, above {maximum}"
)
}
Self::DuplicateComponent { name } => {
write!(formatter, "component {name:?} is covered more than once")
}
Self::MissingCoveredHeader { name } => {
write!(formatter, "covered header {name:?} is absent from the message")
}
Self::NoInputs => formatter.write_str("a signature input header carries no input"),
Self::TooManyInputs { count, maximum } => {
write!(
formatter,
"a signature input header carries {count} inputs, above {maximum}"
)
}
Self::DuplicateLabel { label } => {
write!(formatter, "signature input label {label:?} appears more than once")
}
Self::MissingCreated { label } => {
write!(formatter, "signature input {label:?} omits the required \"created\"")
}
Self::UnknownParameter { name } => {
write!(formatter, "signature input parameter {name:?} is not defined")
}
Self::ParametersOutOfOrder => {
write!(
formatter,
"signature input parameters must appear in the order {PARAMETER_ORDER:?}"
)
}
Self::ParameterOutOfRange { name } => write!(
formatter,
"signature input parameter {name:?} exceeds maximum {MAX_PARAMETER_INTEGER}"
),
Self::InvalidParameterValue { name } => write!(
formatter,
"signature input parameter {name:?} may not carry a backslash"
),
Self::Malformed { reason, offset } => {
write!(formatter, "malformed signature input at offset {offset}: {reason}")
}
Self::Header { .. } => formatter.write_str("a covered component is not a valid header name"),
Self::Field { .. } => formatter.write_str("a signature input parameter value is invalid"),
}
}
}
impl Error for SignatureInputError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::Header { source } => Some(source),
Self::Field { source } => Some(source),
_ => None,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::header::HeaderValue;
use std::error::Error;
const KEYID: &str = "DN54yRad_BTqgZYUSi_NthRBQrxSnqQdJXWI5UHcGOQt";
const RESOURCE: &str = "EWJkQCFvKuyxZi582yJPb0wcwuW3VXmFNuvbQuBpgmIs";
const STAMP: &str = "2022-09-24T00:05:48.196795+00:00";
fn headers() -> Result<Headers, Box<dyn Error>> {
Ok(Headers::from_pairs([
(HeaderName::new("Content-Type")?, HeaderValue::new("application/json")?),
(HeaderName::new("Signify-Resource")?, HeaderValue::new(RESOURCE)?),
(HeaderName::new("Signify-Timestamp")?, HeaderValue::new(STAMP)?),
])?)
}
fn default_input() -> Result<SignatureInput, Box<dyn Error>> {
Ok(
SignatureInputBuilder::new(InputLabel::signify(), default_components()?, 1_609_459_200)
.key_identifier(FieldText::new(KEYID)?)
.algorithm(FieldText::new(ED25519_ALGORITHM)?)
.build()?,
)
}
#[test]
fn the_default_components_are_in_order() -> Result<(), Box<dyn Error>> {
let components = default_components()?;
let names: Vec<&str> = components.iter().map(SignatureComponent::as_str).collect();
assert_eq!(names, ["@method", "@path", "signify-resource", "signify-timestamp"]);
Ok(())
}
#[test]
fn the_base_and_the_header_spell_the_same_input_differently() -> Result<(), Box<dyn Error>> {
let input = default_input()?;
let target = RequestTarget::new("POST", "/boot")?;
let base = input.signature_base(&target, &headers()?)?;
assert_eq!(
base.as_str(),
concat!(
"\"@method\": POST\n",
"\"@path\": /boot\n",
"\"signify-resource\": EWJkQCFvKuyxZi582yJPb0wcwuW3VXmFNuvbQuBpgmIs\n",
"\"signify-timestamp\": 2022-09-24T00:05:48.196795+00:00\n",
"\"@signature-params: (@method @path signify-resource signify-timestamp);",
"created=1609459200;keyid=DN54yRad_BTqgZYUSi_NthRBQrxSnqQdJXWI5UHcGOQt;alg=ed25519\"",
)
);
assert_eq!(base.as_bytes(), base.as_str().as_bytes());
assert_eq!(base.to_string(), base.as_str());
let header = SignatureInputHeader::new(vec![input])?;
assert_eq!(
header.to_header_value()?,
concat!(
"signify=(\"@method\" \"@path\" \"signify-resource\" \"signify-timestamp\");",
"created=1609459200;keyid=\"DN54yRad_BTqgZYUSi_NthRBQrxSnqQdJXWI5UHcGOQt\";alg=\"ed25519\"",
)
);
Ok(())
}
#[test]
fn a_header_round_trips_through_parsing() -> Result<(), Box<dyn Error>> {
let header = SignatureInputHeader::new(vec![
SignatureInputBuilder::new(InputLabel::signify(), default_components()?, 1_609_459_200)
.expires(1_609_545_600)
.nonce(FieldText::new("0AAxyz")?)
.key_identifier(FieldText::new(KEYID)?)
.context(FieldText::new("keria")?)
.algorithm(FieldText::new(ED25519_ALGORITHM)?)
.build()?,
])?;
let rendered = header.to_header_value()?;
let parsed = SignatureInputHeader::parse(&rendered)?;
assert_eq!(parsed, header);
assert_eq!(parsed.to_header_value()?, rendered);
assert_eq!(rendered.parse::<SignatureInputHeader>()?, header);
assert_eq!(SignatureInputHeader::try_from(rendered.as_str())?, header);
let input = parsed.find(&InputLabel::signify()).ok_or("no input")?;
assert_eq!(input.created(), 1_609_459_200);
assert_eq!(input.expires(), Some(1_609_545_600));
assert_eq!(input.nonce(), Some("0AAxyz"));
assert_eq!(input.key_identifier(), Some(KEYID));
assert_eq!(input.context(), Some("keria"));
assert_eq!(input.algorithm(), Some(ED25519_ALGORITHM));
assert_eq!(input.label().as_str(), "signify");
assert_eq!(input.components().len(), 4);
assert!(parsed.find(&InputLabel::new("other")?).is_none());
Ok(())
}
#[test]
fn several_inputs_are_comma_separated() -> Result<(), Box<dyn Error>> {
let value = "signify=(\"@method\");created=1609459200, other=(\"@path\");created=1609459201";
let header = SignatureInputHeader::parse(value)?;
assert_eq!(header.inputs().len(), 2);
assert_eq!(header.to_header_value()?, value);
assert_eq!(SignatureInputHeader::parse(&value.replace(", ", ","))?, header);
Ok(())
}
#[test]
fn a_missing_covered_header_is_refused() -> Result<(), Box<dyn Error>> {
let input = SignatureInputBuilder::new(
InputLabel::signify(),
vec![SignatureComponent::Method, SignatureComponent::new("x-absent")?],
1,
)
.build()?;
assert!(matches!(
input.signature_base(&RequestTarget::new("GET", "/x")?, &headers()?),
Err(SignatureInputError::MissingCoveredHeader { name }) if name == "x-absent"
));
Ok(())
}
#[test]
fn covered_header_lookup_ignores_case_but_the_base_keeps_it() -> Result<(), Box<dyn Error>> {
let input = SignatureInputBuilder::new(
InputLabel::signify(),
vec![SignatureComponent::new("SIGNIFY-RESOURCE")?],
1,
)
.build()?;
let base = input.signature_base(&RequestTarget::new("GET", "/x")?, &headers()?)?;
assert!(base.as_str().starts_with(&format!("\"SIGNIFY-RESOURCE\": {RESOURCE}")));
Ok(())
}
#[test]
fn only_the_two_implemented_derived_components_exist() -> Result<(), Box<dyn Error>> {
assert_eq!(SignatureComponent::new("@method")?, SignatureComponent::Method);
assert_eq!(SignatureComponent::new("@path")?, SignatureComponent::Path);
assert_eq!(SignatureComponent::from_str("@path")?.to_string(), "@path");
for name in ["@authority", "@query", "@target-uri", "@"] {
assert!(
matches!(
SignatureComponent::new(name),
Err(SignatureInputError::UnknownDerivedComponent { .. })
),
"{name:?} was accepted",
);
}
assert!(matches!(
SignatureComponent::new("a b"),
Err(SignatureInputError::Header { .. })
));
Ok(())
}
#[test]
fn labels_follow_the_dictionary_key_grammar() -> Result<(), Box<dyn Error>> {
assert_eq!(InputLabel::new("sig0")?.as_str(), "sig0");
assert_eq!(InputLabel::new("*x")?.to_string(), "*x");
assert_eq!(InputLabel::from_str("signify")?, InputLabel::signify());
for label in ["Signify", "0sig", "sig 0", "", "-sig", "sig=0"] {
assert!(
matches!(InputLabel::new(label), Err(SignatureInputError::InvalidLabel { .. })),
"{label:?} was accepted",
);
}
assert!(InputLabel::new("a".repeat(MAX_LABEL_BYTES + 1)).is_err());
Ok(())
}
#[test]
fn request_targets_cannot_forge_a_base_line() -> Result<(), Box<dyn Error>> {
let target = RequestTarget::new("POST", "/identifiers/aid1")?;
assert_eq!(target.method(), "POST");
assert_eq!(target.path(), "/identifiers/aid1");
assert_eq!(RequestTarget::new("GET", "/oobi/EB%2Fa")?.path(), "/oobi/EB%2Fa");
for path in [
"/a\n\"@method\": DELETE",
"relative",
"",
"/a b",
"/a?limit=1",
"/a#top",
"/a\"b",
] {
assert!(
matches!(
RequestTarget::new("GET", path),
Err(SignatureInputError::InvalidRequestPath { .. })
),
"{path:?} was accepted",
);
}
for method in ["", "GET POST", "GE\nT", "G:T"] {
assert!(
matches!(
RequestTarget::new(method, "/x"),
Err(SignatureInputError::InvalidRequestMethod { .. })
),
"{method:?} was accepted",
);
}
assert!(RequestTarget::new("GET", &format!("/{}", "a".repeat(MAX_REQUEST_PATH_BYTES))).is_err());
assert!(RequestTarget::new(&"A".repeat(MAX_REQUEST_METHOD_BYTES + 1), "/x").is_err());
Ok(())
}
#[test]
fn empty_and_repeated_coverage_is_refused() -> Result<(), Box<dyn Error>> {
assert!(matches!(
SignatureInputBuilder::new(InputLabel::signify(), Vec::new(), 1).build(),
Err(SignatureInputError::NoComponents)
));
assert!(matches!(
SignatureInputHeader::parse("signify=();created=1"),
Err(SignatureInputError::NoComponents)
));
assert!(matches!(
SignatureInputBuilder::new(
InputLabel::signify(),
vec![
SignatureComponent::new("signify-resource")?,
SignatureComponent::new("Signify-Resource")?,
],
1,
)
.build(),
Err(SignatureInputError::DuplicateComponent { .. })
));
assert!(matches!(
SignatureInputBuilder::new(
InputLabel::signify(),
vec![SignatureComponent::Method; MAX_COMPONENTS + 1],
1,
)
.build(),
Err(SignatureInputError::TooManyComponents { .. })
));
Ok(())
}
#[test]
fn headers_hold_at_least_one_input_and_unique_labels() -> Result<(), Box<dyn Error>> {
assert!(matches!(
SignatureInputHeader::new(Vec::new()),
Err(SignatureInputError::NoInputs)
));
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");created=1, signify=(\"@path\");created=2"),
Err(SignatureInputError::DuplicateLabel { .. })
));
let inputs = (0..=MAX_INPUTS)
.map(|position| {
Ok(SignatureInputBuilder::new(
InputLabel::new(format!("sig{position}"))?,
vec![SignatureComponent::Method],
1,
)
.build()?)
})
.collect::<Result<Vec<_>, Box<dyn Error>>>()?;
assert!(matches!(
SignatureInputHeader::new(inputs),
Err(SignatureInputError::TooManyInputs { .. })
));
Ok(())
}
#[test]
fn parameters_are_required_ordered_and_known() {
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");alg=\"ed25519\""),
Err(SignatureInputError::MissingCreated { .. })
));
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");created=1;alg=\"ed25519\";keyid=\"x\""),
Err(SignatureInputError::ParametersOutOfOrder)
));
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");created=1;created=2"),
Err(SignatureInputError::ParametersOutOfOrder)
));
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");created=1;tag=\"x\""),
Err(SignatureInputError::UnknownParameter { name }) if name == "tag"
));
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");created=-1"),
Err(SignatureInputError::Malformed { .. })
));
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");created=01"),
Err(SignatureInputError::Malformed { .. })
));
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");created=9999999999999999"),
Err(SignatureInputError::ParameterOutOfRange { .. })
));
}
#[test]
fn malformed_values_are_typed_errors() {
for value in [
"",
"signify",
"signify=",
"signify=(",
"signify=(\"@method\"",
"signify=(\"@method\")",
"signify=(@method);created=1",
"signify=(\"@method\"\"@path\");created=1",
"signify=(\"@method\");created=1;",
"signify=(\"@method\");created",
"signify=(\"@method\");created=1 trailing",
"signify=(\"a\\\"b\");created=1",
"signify=(\"@method\");created=1;keyid=x",
"signify=(\"@method\");created=1;keyid=\"a b\"",
] {
let parsed = SignatureInputHeader::parse(value);
assert!(
matches!(
parsed,
Err(SignatureInputError::Malformed { .. }
| SignatureInputError::InvalidLabel { .. }
| SignatureInputError::MissingCreated { .. }
| SignatureInputError::NoComponents
| SignatureInputError::UnknownDerivedComponent { .. }
| SignatureInputError::Field { .. })
),
"{value:?} produced {parsed:?}",
);
}
}
#[test]
fn oversized_input_is_bounded() -> Result<(), Box<dyn Error>> {
assert!(matches!(
SignatureInputHeader::parse(&"a".repeat(MAX_SIGNATURE_INPUT_BYTES + 1)),
Err(SignatureInputError::SignatureInputTooLong { .. })
));
let mut headers = Headers::new();
let mut components = Vec::new();
for position in 0..MAX_COMPONENTS {
let name = HeaderName::new(format!("x-{position}"))?;
headers.insert(name.clone(), HeaderValue::new("v".repeat(MAX_HEADER_VALUE))?)?;
components.push(SignatureComponent::Header(name));
}
let input = SignatureInputBuilder::new(InputLabel::signify(), components, 1).build()?;
assert!(matches!(
input.signature_base(&RequestTarget::new("GET", "/x")?, &headers),
Err(SignatureInputError::SignatureBaseTooLong { .. })
));
Ok(())
}
const MAX_HEADER_VALUE: usize = 2048;
#[test]
fn parameter_values_cannot_forge_a_parameter() {
for text in ["a\"b", "a;alg=forged", "a b", "a,b", "a=b"] {
assert!(FieldText::new(text).is_err(), "{text:?} was accepted");
}
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");created=1;keyid=\"a;alg=forged\""),
Err(SignatureInputError::Field { .. })
));
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");created=1;keyid=\"a\\\"b\""),
Err(SignatureInputError::Malformed { .. })
));
}
#[test]
fn a_parameter_value_may_not_carry_a_backslash() -> Result<(), Box<dyn Error>> {
assert!(matches!(
SignatureInputBuilder::new(InputLabel::signify(), vec![SignatureComponent::Method], 1)
.nonce(FieldText::new("\\")?)
.build(),
Err(SignatureInputError::InvalidParameterValue { name: "nonce" })
));
for text in ["a\\b", "\\"] {
assert!(
SignatureInputBuilder::new(InputLabel::signify(), vec![SignatureComponent::Method], 1)
.key_identifier(FieldText::new(text)?)
.build()
.is_err(),
"{text:?} was accepted",
);
}
assert!(matches!(
SignatureInputHeader::parse("signify=(\"@method\");created=1;nonce=\"\\\""),
Err(SignatureInputError::Malformed { .. })
));
Ok(())
}
#[test]
fn errors_carry_readable_text_and_sources() {
for error in [
SignatureInputError::SignatureInputTooLong {
length: 1,
maximum: MAX_SIGNATURE_INPUT_BYTES,
},
SignatureInputError::SignatureBaseTooLong {
length: 1,
maximum: MAX_SIGNATURE_BASE_BYTES,
},
SignatureInputError::InvalidLabel { label: "X".to_owned() },
SignatureInputError::UnknownDerivedComponent {
name: "@authority".to_owned(),
},
SignatureInputError::InvalidRequestMethod {
method: "a b".to_owned(),
},
SignatureInputError::InvalidRequestPath { path: "x".to_owned() },
SignatureInputError::NoComponents,
SignatureInputError::TooManyComponents {
count: 1,
maximum: MAX_COMPONENTS,
},
SignatureInputError::DuplicateComponent { name: "x".to_owned() },
SignatureInputError::MissingCoveredHeader { name: "x".to_owned() },
SignatureInputError::NoInputs,
SignatureInputError::TooManyInputs {
count: 1,
maximum: MAX_INPUTS,
},
SignatureInputError::DuplicateLabel {
label: "signify".to_owned(),
},
SignatureInputError::MissingCreated {
label: "signify".to_owned(),
},
SignatureInputError::UnknownParameter { name: "tag".to_owned() },
SignatureInputError::ParametersOutOfOrder,
SignatureInputError::ParameterOutOfRange { name: "time" },
SignatureInputError::InvalidParameterValue { name: "nonce" },
SignatureInputError::Malformed { reason: "x", offset: 0 },
] {
assert_ne!(error.to_string(), "");
assert!(error.source().is_none());
}
let layered = SignatureInputError::from(HeaderError::EmptyName);
assert!(layered.source().is_some());
let layered = SignatureInputError::from(SignatureFieldError::EmptyFieldText);
assert!(layered.source().is_some());
}
}