use alloc::borrow::ToOwned;
use alloc::boxed::Box;
use alloc::format;
use alloc::string::{String, ToString};
use alloc::vec::Vec;
use core::fmt;
use base64::Engine as _;
use serde::{Deserialize, Serialize};
use serde_json::value::RawValue;
use super::frame::{Frame, MessageTypeId};
pub const SIGNED_SUFFIX: &str = "-Signed";
const B64: base64::engine::general_purpose::GeneralPurpose =
base64::engine::general_purpose::URL_SAFE_NO_PAD;
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Algorithm {
Es256,
Rs256,
Rs384,
}
impl Algorithm {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Algorithm::Es256 => "ES256",
Algorithm::Rs256 => "RS256",
Algorithm::Rs384 => "RS384",
}
}
#[must_use]
pub fn from_wire(value: &str) -> Option<Self> {
Some(match value {
"ES256" => Algorithm::Es256,
"RS256" => Algorithm::Rs256,
"RS384" => Algorithm::Rs384,
_ => return None,
})
}
}
impl fmt::Display for Algorithm {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct ProtectedHeader {
pub alg: String,
#[serde(rename = "OCPPAction")]
pub ocpp_action: String,
#[serde(rename = "OCPPMessageTypedId")]
pub ocpp_message_typed_id: u8,
#[serde(rename = "x5t#S256", default, skip_serializing_if = "Option::is_none")]
pub x5t_s256: Option<String>,
#[serde(flatten)]
pub extra: serde_json::Map<String, serde_json::Value>,
}
impl ProtectedHeader {
#[must_use]
pub fn new(algorithm: Algorithm, action: &str, message_type: MessageTypeId) -> Self {
Self {
alg: algorithm.as_str().to_owned(),
ocpp_action: action.to_owned(),
ocpp_message_typed_id: message_type.number(),
x5t_s256: None,
extra: serde_json::Map::new(),
}
}
#[must_use]
pub fn algorithm(&self) -> Option<Algorithm> {
Algorithm::from_wire(&self.alg)
}
#[must_use]
pub fn with_thumbprint(mut self, x5t_s256: impl Into<String>) -> Self {
self.x5t_s256 = Some(x5t_s256.into());
self
}
fn check_critical(&self) -> Result<(), SignatureError> {
let Some(crit) = self.extra.get("crit") else {
return Ok(());
};
let Some(names) = crit.as_array() else {
return Err(SignatureError::UnsupportedCriticalHeader(crit.to_string()));
};
match names.first() {
Some(name) => Err(SignatureError::UnsupportedCriticalHeader(
name.as_str().unwrap_or("?").to_owned(),
)),
None => Ok(()),
}
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Jws {
pub protected: String,
pub payload: String,
pub signature: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub header: Option<serde_json::Map<String, serde_json::Value>>,
}
impl Jws {
#[must_use]
pub fn signing_input(&self) -> String {
format!("{}.{}", self.protected, self.payload)
}
pub fn header(&self) -> Result<ProtectedHeader, SignatureError> {
let bytes = B64
.decode(&self.protected)
.map_err(|_| SignatureError::Malformed)?;
serde_json::from_slice(&bytes).map_err(|_| SignatureError::Malformed)
}
pub fn payload_json(&self) -> Result<Box<RawValue>, SignatureError> {
let bytes = B64
.decode(&self.payload)
.map_err(|_| SignatureError::Malformed)?;
let text = String::from_utf8(bytes).map_err(|_| SignatureError::Malformed)?;
RawValue::from_string(text).map_err(|_| SignatureError::Malformed)
}
pub fn signature_bytes(&self) -> Result<Vec<u8>, SignatureError> {
B64.decode(&self.signature)
.map_err(|_| SignatureError::Malformed)
}
pub fn to_json(&self) -> Result<Box<RawValue>, SignatureError> {
serde_json::value::to_raw_value(self).map_err(|_| SignatureError::Malformed)
}
pub fn parse(json: &RawValue) -> Result<Self, SignatureError> {
serde_json::from_str(json.get()).map_err(|_| SignatureError::Malformed)
}
}
pub trait Signer {
fn algorithm(&self) -> Algorithm;
fn thumbprint(&self) -> Option<String> {
None
}
fn sign(&self, signing_input: &[u8]) -> Result<Vec<u8>, SignatureError>;
}
pub trait Verifier {
fn verify(
&self,
header: &ProtectedHeader,
signing_input: &[u8],
signature: &[u8],
) -> Result<(), SignatureError>;
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SignaturePolicy {
Required,
Optional,
}
pub struct AcceptAnySignature;
impl Verifier for AcceptAnySignature {
fn verify(&self, _: &ProtectedHeader, _: &[u8], _: &[u8]) -> Result<(), SignatureError> {
Ok(())
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum SignatureError {
Malformed,
UnsupportedAlgorithm(String),
Invalid,
KeyUnavailable(String),
HeaderMismatch {
expected: String,
found: String,
},
NotSignable(MessageTypeId),
Unsigned,
UnsupportedCriticalHeader(String),
}
impl fmt::Display for SignatureError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
SignatureError::Malformed => f.write_str("the signed payload is not a valid JWS"),
SignatureError::UnsupportedAlgorithm(alg) => {
write!(f, "{alg:?} is not an algorithm OCPP permits (Part 4 §7.3)")
}
SignatureError::Invalid => f.write_str("the signature did not verify"),
SignatureError::KeyUnavailable(why) => write!(f, "signing key unavailable: {why}"),
SignatureError::HeaderMismatch { expected, found } => {
write!(
f,
"the protected header says {found}, but the frame says {expected}"
)
}
SignatureError::NotSignable(message_type) => {
write!(f, "a {message_type} has no defined signed form")
}
SignatureError::Unsigned => {
f.write_str("the frame carries no signature, and one is required")
}
SignatureError::UnsupportedCriticalHeader(name) => write!(
f,
"the protected header marks {name:?} critical, and it is not understood (RFC 7515 §4.1.11)"
),
}
}
}
#[cfg(feature = "std")]
impl std::error::Error for SignatureError {}
pub fn sign_payload(
payload: &RawValue,
action: &str,
message_type: MessageTypeId,
signer: &dyn Signer,
) -> Result<Jws, SignatureError> {
let mut header = ProtectedHeader::new(signer.algorithm(), action, message_type);
header.x5t_s256 = signer.thumbprint();
let header_json = serde_json::to_vec(&header).map_err(|_| SignatureError::Malformed)?;
let jws = Jws {
protected: B64.encode(&header_json),
payload: B64.encode(payload.get().as_bytes()),
signature: String::new(),
header: None,
};
let signature = signer.sign(jws.signing_input().as_bytes())?;
Ok(Jws {
signature: B64.encode(&signature),
..jws
})
}
pub fn verify_payload(
jws: &Jws,
action: &str,
message_type: MessageTypeId,
verifier: &dyn Verifier,
) -> Result<Box<RawValue>, SignatureError> {
let header = jws.header()?;
if header.algorithm().is_none() {
return Err(SignatureError::UnsupportedAlgorithm(header.alg.clone()));
}
header.check_critical()?;
if header.ocpp_action != action {
return Err(SignatureError::HeaderMismatch {
expected: action.to_owned(),
found: header.ocpp_action.clone(),
});
}
if header.ocpp_message_typed_id != message_type.number() {
return Err(SignatureError::HeaderMismatch {
expected: message_type.number().to_string(),
found: header.ocpp_message_typed_id.to_string(),
});
}
verifier.verify(
&header,
jws.signing_input().as_bytes(),
&jws.signature_bytes()?,
)?;
jws.payload_json()
}
#[must_use]
pub fn unsigned_action(action: &str) -> Option<&str> {
action.strip_suffix(SIGNED_SUFFIX)
}
#[must_use]
pub fn is_signed_action(action: &str) -> bool {
action.ends_with(SIGNED_SUFFIX)
}
pub fn sign_frame(
frame: &Frame<'_>,
signer: &dyn Signer,
request_action: Option<&str>,
) -> Result<Frame<'static>, SignatureError> {
let message_type = frame.message_type();
match frame {
Frame::Call {
id,
action,
payload,
}
| Frame::Send {
id,
action,
payload,
} => {
let jws = sign_payload(payload, action, message_type, signer)?;
let signed_action = format!("{action}{SIGNED_SUFFIX}");
let payload = alloc::borrow::Cow::Owned(jws.to_json()?);
Ok(if message_type == MessageTypeId::Call {
Frame::Call {
id: id.clone(),
action: signed_action.into(),
payload,
}
} else {
Frame::Send {
id: id.clone(),
action: signed_action.into(),
payload,
}
})
}
Frame::CallResult { id, payload } => {
let action = request_action.ok_or_else(|| {
SignatureError::KeyUnavailable(
"signing a CALLRESULT needs the action of the CALL it answers".to_owned(),
)
})?;
let jws = sign_payload(payload, action, message_type, signer)?;
Ok(Frame::CallResult {
id: id.clone(),
payload: alloc::borrow::Cow::Owned(jws.to_json()?),
})
}
Frame::CallError { .. } | Frame::CallResultError { .. } => {
Err(SignatureError::NotSignable(message_type))
}
}
}
pub fn verify_frame(
frame: &Frame<'_>,
verifier: &dyn Verifier,
request_action: Option<&str>,
policy: SignaturePolicy,
) -> Result<Frame<'static>, SignatureError> {
let message_type = frame.message_type();
match frame {
Frame::Call {
id,
action,
payload,
}
| Frame::Send {
id,
action,
payload,
} => {
let Some(action) = unsigned_action(action) else {
return unsigned(frame, policy);
};
let jws = Jws::parse(payload)?;
let payload = verify_payload(&jws, action, message_type, verifier)?;
let payload = alloc::borrow::Cow::Owned(payload);
Ok(if message_type == MessageTypeId::Call {
Frame::Call {
id: id.clone(),
action: action.to_owned().into(),
payload,
}
} else {
Frame::Send {
id: id.clone(),
action: action.to_owned().into(),
payload,
}
})
}
Frame::CallResult { id, payload } => {
let Some(action) = request_action else {
return unsigned(frame, policy);
};
let Ok(jws) = Jws::parse(payload) else {
return unsigned(frame, policy);
};
let payload = verify_payload(&jws, action, message_type, verifier)?;
Ok(Frame::CallResult {
id: id.clone(),
payload: alloc::borrow::Cow::Owned(payload),
})
}
Frame::CallError { .. } | Frame::CallResultError { .. } => Ok(frame.clone().into_owned()),
}
}
fn unsigned(frame: &Frame<'_>, policy: SignaturePolicy) -> Result<Frame<'static>, SignatureError> {
match policy {
SignaturePolicy::Required => Err(SignatureError::Unsigned),
SignaturePolicy::Optional => Ok(frame.clone().into_owned()),
}
}
#[cfg(feature = "jws-es256")]
mod es256 {
use super::{Algorithm, B64, ProtectedHeader, SignatureError, Signer, Verifier};
use alloc::string::{String, ToString};
use alloc::vec::Vec;
use base64::Engine as _;
use p256::ecdsa::signature::{Signer as _, Verifier as _};
use p256::ecdsa::{Signature, SigningKey, VerifyingKey};
#[must_use]
pub fn thumbprint(certificate_der: &[u8]) -> String {
use sha2::{Digest as _, Sha256};
B64.encode(Sha256::digest(certificate_der))
}
pub struct Es256Signer {
key: SigningKey,
thumbprint: Option<String>,
}
impl Es256Signer {
#[must_use]
pub fn new(key: SigningKey) -> Self {
Self {
key,
thumbprint: None,
}
}
pub fn from_bytes(bytes: &[u8]) -> Result<Self, SignatureError> {
let key = SigningKey::from_slice(bytes)
.map_err(|error| SignatureError::KeyUnavailable(error.to_string()))?;
Ok(Self::new(key))
}
#[must_use]
pub fn with_certificate(mut self, certificate_der: &[u8]) -> Self {
self.thumbprint = Some(thumbprint(certificate_der));
self
}
#[must_use]
pub fn verifier(&self) -> Es256Verifier {
Es256Verifier::new(*self.key.verifying_key())
}
}
impl Signer for Es256Signer {
fn algorithm(&self) -> Algorithm {
Algorithm::Es256
}
fn thumbprint(&self) -> Option<String> {
self.thumbprint.clone()
}
fn sign(&self, signing_input: &[u8]) -> Result<Vec<u8>, SignatureError> {
let signature: Signature = self.key.sign(signing_input);
Ok(signature.to_bytes().to_vec())
}
}
pub struct Es256Verifier {
key: VerifyingKey,
}
impl Es256Verifier {
#[must_use]
pub fn new(key: VerifyingKey) -> Self {
Self { key }
}
pub fn from_sec1_bytes(bytes: &[u8]) -> Result<Self, SignatureError> {
let key = VerifyingKey::from_sec1_bytes(bytes)
.map_err(|error| SignatureError::KeyUnavailable(error.to_string()))?;
Ok(Self::new(key))
}
}
impl Verifier for Es256Verifier {
fn verify(
&self,
header: &ProtectedHeader,
signing_input: &[u8],
signature: &[u8],
) -> Result<(), SignatureError> {
if header.algorithm() != Some(Algorithm::Es256) {
return Err(SignatureError::UnsupportedAlgorithm(header.alg.clone()));
}
let signature =
Signature::from_slice(signature).map_err(|_| SignatureError::Invalid)?;
self.key
.verify(signing_input, &signature)
.map_err(|_| SignatureError::Invalid)
}
}
}
#[cfg(feature = "jws-es256")]
pub use es256::{Es256Signer, Es256Verifier, thumbprint};
#[cfg(all(test, feature = "jws-es256"))]
mod tests {
use super::*;
use crate::types::MessageId;
use crate::version::Version;
fn key() -> Es256Signer {
Es256Signer::from_bytes(&[7u8; 32])
.unwrap()
.with_certificate(b"a-der-certificate")
}
fn call() -> Frame<'static> {
Frame::Call {
id: MessageId::new("19223201").unwrap(),
action: "BootNotification".into(),
payload: alloc::borrow::Cow::Owned(
RawValue::from_string(r#"{"reason":"PowerUp"}"#.to_owned()).unwrap(),
),
}
}
#[test]
fn a_signed_call_carries_the_suffix_and_round_trips() {
let es256 = key();
let signed = sign_frame(&call(), &es256, None).unwrap();
assert_eq!(signed.action(), Some("BootNotification-Signed"));
assert!(is_signed_action(signed.action().unwrap()));
assert_eq!(
unsigned_action(signed.action().unwrap()),
Some("BootNotification")
);
let text = signed.to_json(Version::V2_1).unwrap();
assert!(text.starts_with(r#"[2,"19223201","BootNotification-Signed","#));
assert_eq!(Frame::parse(&text, Version::V2_1).unwrap(), signed);
let verified =
verify_frame(&signed, &es256.verifier(), None, SignaturePolicy::Required).unwrap();
assert_eq!(verified, call());
}
#[test]
fn the_protected_header_carries_the_ocpp_fields() {
let es256 = key();
let signed = sign_frame(&call(), &es256, None).unwrap();
let jws = Jws::parse(signed.payload().unwrap()).unwrap();
let header = jws.header().unwrap();
assert_eq!(header.algorithm(), Some(Algorithm::Es256));
assert_eq!(header.ocpp_action, "BootNotification");
assert_eq!(header.ocpp_message_typed_id, 2);
assert!(
header.x5t_s256.is_some(),
"x5t#S256 identifies the signing certificate"
);
let raw: serde_json::Value =
serde_json::from_slice(&B64.decode(&jws.protected).unwrap()).unwrap();
assert!(raw.get("OCPPAction").is_some());
assert!(raw.get("OCPPMessageTypedId").is_some());
assert!(raw.get("x5t#S256").is_some());
}
#[test]
fn a_tampered_payload_does_not_verify() {
let es256 = key();
let signed = sign_frame(&call(), &es256, None).unwrap();
let mut jws = Jws::parse(signed.payload().unwrap()).unwrap();
jws.payload = B64.encode(br#"{"reason":"FirmwareUpdate"}"#);
let tampered = Frame::Call {
id: MessageId::new("19223201").unwrap(),
action: "BootNotification-Signed".into(),
payload: alloc::borrow::Cow::Owned(jws.to_json().unwrap()),
};
assert_eq!(
verify_frame(
&tampered,
&es256.verifier(),
None,
SignaturePolicy::Required
)
.unwrap_err(),
SignatureError::Invalid
);
}
#[test]
fn a_signature_cannot_be_moved_to_another_action() {
let es256 = key();
let signed = sign_frame(&call(), &es256, None).unwrap();
let moved = Frame::Call {
id: MessageId::new("19223201").unwrap(),
action: "Heartbeat-Signed".into(),
payload: alloc::borrow::Cow::Owned(signed.payload().unwrap().to_owned()),
};
assert!(matches!(
verify_frame(&moved, &es256.verifier(), None, SignaturePolicy::Required).unwrap_err(),
SignatureError::HeaderMismatch { .. }
));
}
#[test]
fn a_stripped_signature_is_refused_when_signatures_are_required() {
let es256 = key();
let plain = call();
assert_eq!(
verify_frame(&plain, &es256.verifier(), None, SignaturePolicy::Required).unwrap_err(),
SignatureError::Unsigned
);
assert_eq!(
verify_frame(&plain, &es256.verifier(), None, SignaturePolicy::Optional).unwrap(),
plain
);
let result = Frame::CallResult {
id: MessageId::new("19223201").unwrap(),
payload: alloc::borrow::Cow::Owned(
RawValue::from_string(r#"{"status":"Accepted"}"#.to_owned()).unwrap(),
),
};
assert_eq!(
verify_frame(
&result,
&es256.verifier(),
Some("BootNotification"),
SignaturePolicy::Required
)
.unwrap_err(),
SignatureError::Unsigned
);
let error = Frame::CallError {
id: MessageId::new("19223201").unwrap(),
error: crate::rpc::CallError::new(crate::rpc::ErrorCode::GenericError, "").into(),
};
assert!(
verify_frame(&error, &es256.verifier(), None, SignaturePolicy::Required).is_ok(),
"an error frame has no signed form to require"
);
}
#[test]
fn a_critical_header_we_do_not_understand_is_refused() {
let es256 = key();
let signed = sign_frame(&call(), &es256, None).unwrap();
let jws = Jws::parse(signed.payload().unwrap()).unwrap();
let mut header = jws.header().unwrap();
header
.extra
.insert("crit".into(), serde_json::json!(["exp"]));
header.extra.insert("exp".into(), serde_json::json!(0));
let header_json = serde_json::to_vec(&header).unwrap();
let unsigned_jws = Jws {
protected: B64.encode(&header_json),
payload: jws.payload.clone(),
signature: String::new(),
header: None,
};
let signature = es256.sign(unsigned_jws.signing_input().as_bytes()).unwrap();
let critical = Jws {
signature: B64.encode(&signature),
..unsigned_jws
};
assert_eq!(
verify_payload(
&critical,
"BootNotification",
MessageTypeId::Call,
&es256.verifier()
)
.unwrap_err(),
SignatureError::UnsupportedCriticalHeader("exp".to_owned())
);
let mut header = jws.header().unwrap();
header.extra.insert("crit".into(), serde_json::json!([]));
assert!(header.check_critical().is_ok());
}
#[test]
fn a_call_result_is_signed_under_the_requests_action() {
let es256 = key();
let result = Frame::CallResult {
id: MessageId::new("19223201").unwrap(),
payload: alloc::borrow::Cow::Owned(
RawValue::from_string(r#"{"status":"Accepted"}"#.to_owned()).unwrap(),
),
};
assert!(matches!(
sign_frame(&result, &es256, None).unwrap_err(),
SignatureError::KeyUnavailable(_)
));
let signed = sign_frame(&result, &es256, Some("BootNotification")).unwrap();
let verified = verify_frame(
&signed,
&es256.verifier(),
Some("BootNotification"),
SignaturePolicy::Required,
)
.unwrap();
assert_eq!(verified, result);
}
#[test]
fn an_error_frame_has_no_signed_form() {
let es256 = key();
let error = Frame::CallError {
id: MessageId::new("1").unwrap(),
error: crate::rpc::CallError::internal("boom").into(),
};
assert_eq!(
sign_frame(&error, &es256, None).unwrap_err(),
SignatureError::NotSignable(MessageTypeId::CallError)
);
}
#[test]
fn the_none_algorithm_is_refused() {
let mut header = ProtectedHeader::new(Algorithm::Es256, "Heartbeat", MessageTypeId::Call);
header.alg = "none".to_owned();
assert_eq!(header.algorithm(), None);
let jws = Jws {
protected: B64.encode(serde_json::to_vec(&header).unwrap()),
payload: B64.encode(b"{}"),
signature: String::new(),
header: None,
};
assert_eq!(
verify_payload(&jws, "Heartbeat", MessageTypeId::Call, &AcceptAnySignature)
.unwrap_err(),
SignatureError::UnsupportedAlgorithm("none".to_owned())
);
}
}