use base64::Engine;
use base64::engine::general_purpose::{STANDARD, STANDARD_NO_PAD};
use std::fmt;
use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
use crate::internal_core::{Error, Result};
pub(crate) const PROTECTION_KEY_BYTES: usize =
crate::internal_core::contract::VALUE_FORMAT_DATA_PROTECTION_KEY_BYTES;
pub const DATA_PROTECTION_KEY_BYTES: usize = PROTECTION_KEY_BYTES;
pub const CLIENT_ROOT_KEY_BYTES: usize = PROTECTION_KEY_BYTES;
pub use crate::internal_core::contract::MAX_CANONICAL_KEY_BYTES;
pub const MAX_KEY_INPUT_BYTES: usize = MAX_CANONICAL_KEY_BYTES;
pub const MAX_ITEM_ID_BYTES: usize = crate::internal_protocol::MAX_ITEM_ID_BYTES;
const NAMESPACE_HASH_DOMAIN: &[u8] = b"openkache/item-id/namespace-hash/v1";
const PUBLIC_KEY_OR_HASH_DOMAIN: &[u8] = b"openkache/item-id/public-key-or-hash/v1";
#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[non_exhaustive]
pub enum KeyFormat {
#[default]
NamespaceHash,
PublicKeyOrHash,
ByteKeyOrHash,
Hash,
}
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[non_exhaustive]
pub enum KeyType {
Integer,
Text,
Bytes,
}
impl KeyType {
pub const fn name(self) -> &'static str {
match self {
Self::Integer => "integer",
Self::Text => "text",
Self::Bytes => "bytes",
}
}
pub fn from_name(value: &str) -> Option<Self> {
match value {
"integer" => Some(Self::Integer),
"text" => Some(Self::Text),
"bytes" => Some(Self::Bytes),
_ => None,
}
}
}
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct KeySpace {
key_type: KeyType,
format: KeyFormat,
}
impl KeySpace {
pub const fn new(key_type: KeyType) -> Self {
Self {
key_type,
format: KeyFormat::NamespaceHash,
}
}
pub const fn with_format(key_type: KeyType, format: KeyFormat) -> Self {
Self { key_type, format }
}
pub const fn key_type(self) -> KeyType {
self.key_type
}
pub const fn format(self) -> KeyFormat {
self.format
}
pub fn validate(self) -> std::result::Result<(), KeyError> {
if self.format == KeyFormat::ByteKeyOrHash && self.key_type != KeyType::Bytes {
return Err(KeyError::InvalidFormatForKeyType {
format: self.format,
key_type: self.key_type,
});
}
Ok(())
}
pub fn resolve(self, key: impl Into<TypedKey>) -> std::result::Result<ResolvedKey, KeyError> {
self.validate()?;
let key = key.into();
ensure_key_type(self.key_type, key.key_type())?;
if self.format == KeyFormat::ByteKeyOrHash {
if let TypedKey::Bytes(bytes) = key {
return ResolvedKey::from_direct_bytes(bytes);
}
}
ResolvedKey::from_typed(key)
}
pub fn resolve_logical_bytes(self, value: &[u8]) -> std::result::Result<ResolvedKey, KeyError> {
self.validate()?;
if self.format == KeyFormat::ByteKeyOrHash {
return ResolvedKey::from_direct_bytes(value.to_owned());
}
let key = typed_from_logical_bytes(self.key_type, value)?;
ResolvedKey::from_typed(key)
}
pub fn resolve_canonical(
self,
canonical_key: &[u8],
) -> std::result::Result<ResolvedKey, KeyError> {
self.validate()?;
let typed = TypedKey::decode_canonical(canonical_key)?;
ensure_key_type(self.key_type, typed.key_type())?;
if self.format == KeyFormat::ByteKeyOrHash {
if let TypedKey::Bytes(bytes) = typed {
return ResolvedKey::from_direct_bytes(bytes);
}
}
ResolvedKey::from_typed(typed)
}
}
impl fmt::Display for KeyType {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(self.name())
}
}
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct TypedInteger {
negative: bool,
magnitude: Vec<u8>,
}
impl TypedInteger {
pub fn from_i128(value: i128) -> Self {
if value < 0 {
Self::from_parts(true, &value.unsigned_abs().to_be_bytes())
.expect("a native i128 magnitude is always valid")
} else {
Self::from_parts(false, &(value as u128).to_be_bytes())
.expect("a native i128 magnitude is always valid")
}
}
pub fn from_u128(value: u128) -> Self {
Self::from_parts(false, &value.to_be_bytes())
.expect("a native u128 magnitude is always valid")
}
pub fn from_parts(negative: bool, magnitude: &[u8]) -> std::result::Result<Self, KeyError> {
let first_nonzero = magnitude
.iter()
.position(|byte| *byte != 0)
.unwrap_or(magnitude.len());
let magnitude = magnitude[first_nonzero..].to_vec();
if magnitude.len() > MAX_KEY_INPUT_BYTES {
return Err(KeyError::TooLarge {
size: magnitude.len(),
maximum: MAX_KEY_INPUT_BYTES,
});
}
Ok(Self {
negative: negative && !magnitude.is_empty(),
magnitude,
})
}
pub fn from_decimal(value: &str) -> std::result::Result<Self, KeyError> {
let bytes = value.as_bytes();
let (negative, digits) = match bytes.first().copied() {
Some(b'-') => (true, &bytes[1..]),
_ => (false, bytes),
};
if digits.is_empty()
|| digits.iter().any(|digit| !digit.is_ascii_digit())
|| (digits.len() > 1 && digits[0] == b'0')
{
return Err(KeyError::InvalidInteger);
}
if negative && digits == b"0" {
return Err(KeyError::InvalidInteger);
}
let mut magnitude = Vec::new();
for digit in digits {
let mut carry = u16::from(*digit - b'0');
for byte in magnitude.iter_mut().rev() {
let product = u16::from(*byte) * 10 + carry;
*byte = product as u8;
carry = product >> 8;
}
if carry != 0 {
magnitude.insert(0, carry as u8);
}
if magnitude.len() > MAX_KEY_INPUT_BYTES {
return Err(KeyError::TooLarge {
size: magnitude.len(),
maximum: MAX_KEY_INPUT_BYTES,
});
}
}
Self::from_parts(negative, &magnitude)
}
pub const fn is_negative(&self) -> bool {
self.negative
}
pub fn magnitude(&self) -> &[u8] {
&self.magnitude
}
fn as_i64(&self) -> Option<i64> {
let magnitude = as_u64(&self.magnitude)?;
if self.negative {
if magnitude == 1_u64 << 63 {
Some(i64::MIN)
} else {
i64::try_from(magnitude)
.ok()
.and_then(|value| value.checked_neg())
}
} else {
i64::try_from(magnitude).ok()
}
}
fn cbor_bytes(&self, output: &mut Vec<u8>) {
if !self.negative {
if let Some(value) = as_u64(&self.magnitude) {
encode_argument(output, 0, value);
} else {
output.push(0xc2);
encode_argument(output, 2, self.magnitude.len() as u64);
output.extend_from_slice(&self.magnitude);
}
return;
}
let transformed = subtract_one(&self.magnitude);
if let Some(value) = as_u64(&transformed) {
encode_argument(output, 1, value);
} else {
output.push(0xc3);
encode_argument(output, 2, transformed.len() as u64);
output.extend_from_slice(&transformed);
}
}
}
macro_rules! impl_signed_integer {
($($type:ty),+ $(,)?) => {
$(
impl From<$type> for TypedKey {
fn from(value: $type) -> Self {
Self::Integer(TypedInteger::from_i128(value as i128))
}
}
)+
};
}
macro_rules! impl_unsigned_integer {
($($type:ty),+ $(,)?) => {
$(
impl From<$type> for TypedKey {
fn from(value: $type) -> Self {
Self::Integer(TypedInteger::from_u128(value as u128))
}
}
)+
};
}
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[non_exhaustive]
pub enum TypedKey {
Integer(TypedInteger),
Text(String),
Bytes(Vec<u8>),
}
impl TypedKey {
pub fn text(value: impl Into<String>) -> Self {
Self::Text(value.into())
}
pub fn bytes(value: impl Into<Vec<u8>>) -> Self {
Self::Bytes(value.into())
}
pub fn integer(value: i128) -> Self {
Self::Integer(TypedInteger::from_i128(value))
}
pub const fn key_type(&self) -> KeyType {
match self {
Self::Integer(_) => KeyType::Integer,
Self::Text(_) => KeyType::Text,
Self::Bytes(_) => KeyType::Bytes,
}
}
#[deprecated(note = "use key_type")]
pub const fn spec(&self) -> KeyType {
self.key_type()
}
pub fn input_len(&self) -> usize {
match self {
Self::Integer(value) => value.magnitude.len(),
Self::Text(value) => value.len(),
Self::Bytes(value) => value.len(),
}
}
pub fn validate_input_len(&self) -> std::result::Result<(), KeyError> {
let size = self.input_len();
if size > MAX_KEY_INPUT_BYTES {
return Err(KeyError::TooLarge {
size,
maximum: MAX_KEY_INPUT_BYTES,
});
}
Ok(())
}
pub fn canonical_bytes(&self) -> std::result::Result<Vec<u8>, KeyError> {
self.validate_input_len()?;
if let Self::Integer(value) = self {
if value.as_i64().is_none() {
return Err(KeyError::IntegerOutOfRange);
}
}
let mut output = Vec::with_capacity(self.estimated_cbor_size());
match self {
Self::Integer(value) => value.cbor_bytes(&mut output),
Self::Text(value) => {
encode_argument(&mut output, 3, value.len() as u64);
output.extend_from_slice(value.as_bytes());
}
Self::Bytes(value) => {
encode_argument(&mut output, 2, value.len() as u64);
output.extend_from_slice(value);
}
}
if output.len() > MAX_CANONICAL_KEY_BYTES {
return Err(KeyError::TooLarge {
size: output.len(),
maximum: MAX_CANONICAL_KEY_BYTES,
});
}
Ok(output)
}
pub fn decode_canonical(bytes: &[u8]) -> std::result::Result<Self, KeyError> {
if bytes.len() > MAX_CANONICAL_KEY_BYTES {
return Err(KeyError::TooLarge {
size: bytes.len(),
maximum: MAX_CANONICAL_KEY_BYTES,
});
}
let mut cursor = Cursor::new(bytes);
let key = cursor.parse_key()?;
if !cursor.is_empty() {
return Err(KeyError::TrailingBytes);
}
let canonical = key.canonical_bytes()?;
if canonical != bytes {
return Err(KeyError::NonCanonical);
}
Ok(key)
}
fn estimated_cbor_size(&self) -> usize {
match self {
Self::Integer(value) => value.magnitude.len().saturating_add(10),
Self::Text(value) => value.len().saturating_add(9),
Self::Bytes(value) => value.len().saturating_add(9),
}
}
}
fn typed_from_logical_bytes(
key_type: KeyType,
value: &[u8],
) -> std::result::Result<TypedKey, KeyError> {
match key_type {
KeyType::Text => String::from_utf8(value.to_owned())
.map(TypedKey::Text)
.map_err(|_| KeyError::InvalidUtf8),
KeyType::Bytes => Ok(TypedKey::Bytes(value.to_owned())),
KeyType::Integer => {
let value = std::str::from_utf8(value).map_err(|_| KeyError::InvalidInteger)?;
TypedInteger::from_decimal(value).map(TypedKey::Integer)
}
}
}
fn ensure_key_type(expected: KeyType, actual: KeyType) -> std::result::Result<(), KeyError> {
if actual == expected {
Ok(())
} else {
Err(KeyError::KeyTypeMismatch { expected, actual })
}
}
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
pub struct ResolvedKey {
key_type: KeyType,
canonical: Vec<u8>,
legacy_direct: Option<Vec<u8>>,
}
#[derive(Clone, Copy, Debug)]
pub(crate) struct ValidatedCanonicalKey<'a> {
bytes: &'a [u8],
spec: KeyType,
}
impl<'a> ValidatedCanonicalKey<'a> {
pub(crate) const fn bytes(self) -> &'a [u8] {
self.bytes
}
pub(crate) const fn spec(self) -> KeyType {
self.spec
}
}
pub(crate) fn validate_canonical_key(
bytes: &[u8],
) -> std::result::Result<ValidatedCanonicalKey<'_>, KeyError> {
if bytes.len() > MAX_CANONICAL_KEY_BYTES {
return Err(KeyError::TooLarge {
size: bytes.len(),
maximum: MAX_CANONICAL_KEY_BYTES,
});
}
let typed = TypedKey::decode_canonical(bytes)?;
Ok(ValidatedCanonicalKey {
bytes,
spec: typed.key_type(),
})
}
impl ResolvedKey {
pub fn from_typed(key: impl Into<TypedKey>) -> std::result::Result<Self, KeyError> {
let typed = key.into();
let canonical = typed.canonical_bytes()?;
Ok(Self {
key_type: typed.key_type(),
canonical,
legacy_direct: None,
})
}
fn from_direct_bytes(bytes: Vec<u8>) -> std::result::Result<Self, KeyError> {
if bytes.len() > MAX_KEY_INPUT_BYTES {
return Err(KeyError::TooLarge {
size: bytes.len(),
maximum: MAX_KEY_INPUT_BYTES,
});
}
let canonical = TypedKey::Bytes(bytes.clone()).canonical_bytes()?;
Ok(Self {
key_type: KeyType::Bytes,
canonical,
legacy_direct: Some(bytes),
})
}
pub fn from_canonical(bytes: &[u8]) -> std::result::Result<Self, KeyError> {
let typed = TypedKey::decode_canonical(bytes)?;
Ok(Self {
key_type: typed.key_type(),
canonical: bytes.to_owned(),
legacy_direct: None,
})
}
pub const fn key_type(&self) -> KeyType {
self.key_type
}
pub fn canonical_bytes(&self) -> &[u8] {
&self.canonical
}
pub fn into_canonical_bytes(self) -> Vec<u8> {
self.canonical
}
}
impl From<TypedInteger> for TypedKey {
fn from(value: TypedInteger) -> Self {
Self::Integer(value)
}
}
impl From<String> for TypedKey {
fn from(value: String) -> Self {
Self::Text(value)
}
}
impl From<&str> for TypedKey {
fn from(value: &str) -> Self {
Self::Text(value.to_owned())
}
}
impl From<Vec<u8>> for TypedKey {
fn from(value: Vec<u8>) -> Self {
Self::Bytes(value)
}
}
impl From<&[u8]> for TypedKey {
fn from(value: &[u8]) -> Self {
Self::Bytes(value.to_owned())
}
}
impl From<&Vec<u8>> for TypedKey {
fn from(value: &Vec<u8>) -> Self {
Self::Bytes(value.clone())
}
}
impl<const N: usize> From<[u8; N]> for TypedKey {
fn from(value: [u8; N]) -> Self {
Self::Bytes(value.to_vec())
}
}
impl<const N: usize> From<&[u8; N]> for TypedKey {
fn from(value: &[u8; N]) -> Self {
Self::Bytes(value.to_vec())
}
}
impl_signed_integer!(i8, i16, i32, i64, i128, isize);
impl_unsigned_integer!(u8, u16, u32, u64, u128, usize);
fn encode_argument(output: &mut Vec<u8>, major: u8, value: u64) {
debug_assert!(major <= 7);
let prefix = major << 5;
if value <= 23 {
output.push(prefix | value as u8);
} else if value <= u8::MAX as u64 {
output.push(prefix | 24);
output.push(value as u8);
} else if value <= u16::MAX as u64 {
output.push(prefix | 25);
output.extend_from_slice(&(value as u16).to_be_bytes());
} else if value <= u32::MAX as u64 {
output.push(prefix | 26);
output.extend_from_slice(&(value as u32).to_be_bytes());
} else {
output.push(prefix | 27);
output.extend_from_slice(&value.to_be_bytes());
}
}
fn as_u64(magnitude: &[u8]) -> Option<u64> {
if magnitude.len() > 8 {
return None;
}
let mut value = 0_u64;
for byte in magnitude {
value = (value << 8) | u64::from(*byte);
}
Some(value)
}
fn subtract_one(magnitude: &[u8]) -> Vec<u8> {
debug_assert!(!magnitude.is_empty());
let mut output = magnitude.to_vec();
for byte in output.iter_mut().rev() {
if *byte != 0 {
*byte -= 1;
break;
}
*byte = u8::MAX;
}
let first_nonzero = output
.iter()
.position(|byte| *byte != 0)
.unwrap_or(output.len());
output[first_nonzero..].to_vec()
}
struct Cursor<'a> {
bytes: &'a [u8],
position: usize,
}
impl<'a> Cursor<'a> {
const fn new(bytes: &'a [u8]) -> Self {
Self { bytes, position: 0 }
}
const fn is_empty(&self) -> bool {
self.position == self.bytes.len()
}
fn read_byte(&mut self) -> std::result::Result<u8, KeyError> {
let byte = self
.bytes
.get(self.position)
.copied()
.ok_or(KeyError::Truncated)?;
self.position += 1;
Ok(byte)
}
fn read_exact(&mut self, length: usize) -> std::result::Result<&'a [u8], KeyError> {
let end = self
.position
.checked_add(length)
.ok_or(KeyError::Overflow)?;
let bytes = self
.bytes
.get(self.position..end)
.ok_or(KeyError::Truncated)?;
self.position = end;
Ok(bytes)
}
fn read_argument(&mut self, additional: u8) -> std::result::Result<(u64, bool), KeyError> {
match additional {
value @ 0..=23 => Ok((u64::from(value), true)),
24 => {
let value = u64::from(self.read_byte()?);
Ok((value, value >= 24))
}
25 => {
let bytes: [u8; 2] = self.read_exact(2)?.try_into().unwrap();
let value = u64::from(u16::from_be_bytes(bytes));
Ok((value, value > u64::from(u8::MAX)))
}
26 => {
let bytes: [u8; 4] = self.read_exact(4)?.try_into().unwrap();
let value = u64::from(u32::from_be_bytes(bytes));
Ok((value, value > u64::from(u16::MAX)))
}
27 => {
let bytes: [u8; 8] = self.read_exact(8)?.try_into().unwrap();
let value = u64::from_be_bytes(bytes);
Ok((value, value > u64::from(u32::MAX)))
}
_ => Err(KeyError::UnsupportedType),
}
}
fn parse_header(&mut self) -> std::result::Result<(u8, u64), KeyError> {
let header = self.read_byte()?;
let major = header >> 5;
let additional = header & 0x1f;
let (value, preferred) = self.read_argument(additional)?;
if !preferred {
return Err(KeyError::NonCanonical);
}
Ok((major, value))
}
fn parse_bytes(&mut self, length: u64) -> std::result::Result<Vec<u8>, KeyError> {
let length = usize::try_from(length).map_err(|_| KeyError::Overflow)?;
if length > MAX_KEY_INPUT_BYTES {
return Err(KeyError::TooLarge {
size: length,
maximum: MAX_KEY_INPUT_BYTES,
});
}
Ok(self.read_exact(length)?.to_vec())
}
fn parse_key(&mut self) -> std::result::Result<TypedKey, KeyError> {
let header = self
.bytes
.get(self.position)
.copied()
.ok_or(KeyError::Truncated)?;
let major = header >> 5;
if major == 6 {
return Err(KeyError::UnsupportedType);
}
let (major, argument) = self.parse_header()?;
match major {
0 => {
if argument > i64::MAX as u64 {
return Err(KeyError::IntegerOutOfRange);
}
Ok(TypedKey::Integer(TypedInteger::from_u128(u128::from(
argument,
))))
}
1 => {
if argument > i64::MAX as u64 {
return Err(KeyError::IntegerOutOfRange);
}
Ok(TypedKey::Integer(TypedInteger::from_parts(
true,
&u128::from(argument)
.checked_add(1)
.ok_or(KeyError::Overflow)?
.to_be_bytes(),
)?))
}
2 => Ok(TypedKey::Bytes(self.parse_bytes(argument)?)),
3 => {
let bytes = self.parse_bytes(argument)?;
let value = String::from_utf8(bytes).map_err(|_| KeyError::InvalidUtf8)?;
Ok(TypedKey::Text(value))
}
_ => Err(KeyError::UnsupportedType),
}
}
}
#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
#[non_exhaustive]
pub enum KeyError {
#[error("key input is too large: {size} bytes exceeds {maximum}")]
TooLarge {
size: usize,
maximum: usize,
},
#[error("key type {actual} does not match configured key type {expected}")]
KeyTypeMismatch {
expected: KeyType,
actual: KeyType,
},
#[error("key type {actual} does not match key spec {expected}")]
KeySpecMismatch {
expected: KeyType,
actual: KeyType,
},
#[error("key format {format:?} requires key type bytes, got {key_type:?}")]
InvalidFormatForKeyType {
format: KeyFormat,
key_type: KeyType,
},
#[error("canonical key contains trailing bytes")]
TrailingBytes,
#[error("canonical key is not deterministic preferred CBOR")]
NonCanonical,
#[error("canonical key contains an unsupported CBOR item")]
UnsupportedType,
#[error("text key is not valid UTF-8")]
InvalidUtf8,
#[error("integer key is not canonical signed decimal text")]
InvalidInteger,
#[error("canonical key is truncated")]
Truncated,
#[error("integer key is outside the signed i64 range")]
IntegerOutOfRange,
#[error("namespace ID must be a positive server-assigned identity")]
InvalidNamespace,
#[error("canonical key length or integer argument overflows")]
Overflow,
}
pub fn canonical_key_bytes(
key_type: KeyType,
key: impl Into<TypedKey>,
) -> std::result::Result<Vec<u8>, KeyError> {
KeySpace::new(key_type)
.resolve(key)
.map(ResolvedKey::into_canonical_bytes)
}
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct ItemId {
len: u8,
bytes: [u8; MAX_ITEM_ID_BYTES],
}
impl ItemId {
pub fn from_bytes(bytes: impl AsRef<[u8]>) -> Self {
Self::from_slice(bytes.as_ref()).expect("item ID exceeds the wire length limit")
}
pub fn from_slice(bytes: &[u8]) -> Result<Self> {
if bytes.len() > MAX_ITEM_ID_BYTES {
return Err(Error::configuration(
"item_id",
format!(
"must contain at most {MAX_ITEM_ID_BYTES} bytes, got {}",
bytes.len()
),
));
}
let mut item_id = Self {
len: bytes.len() as u8,
bytes: [0; MAX_ITEM_ID_BYTES],
};
item_id.bytes[..bytes.len()].copy_from_slice(bytes);
Ok(item_id)
}
pub fn exact(bytes: &[u8]) -> Result<Self> {
Self::from_slice(bytes)
}
pub fn as_bytes(&self) -> &[u8] {
&self.bytes[..self.len as usize]
}
pub const fn len(&self) -> usize {
self.len as usize
}
pub const fn is_empty(&self) -> bool {
self.len == 0
}
pub fn into_bytes(self) -> Vec<u8> {
self.as_bytes().to_vec()
}
pub(crate) fn into_protocol(self) -> crate::internal_protocol::ItemId {
crate::internal_protocol::ItemId::from_slice(self.as_bytes())
.expect("client ItemId was validated before protocol conversion")
}
}
impl AsRef<[u8]> for ItemId {
fn as_ref(&self) -> &[u8] {
self.as_bytes()
}
}
impl From<[u8; MAX_ITEM_ID_BYTES]> for ItemId {
fn from(bytes: [u8; MAX_ITEM_ID_BYTES]) -> Self {
Self::from_bytes(bytes)
}
}
impl TryFrom<&[u8]> for ItemId {
type Error = Error;
fn try_from(bytes: &[u8]) -> Result<Self> {
Self::from_slice(bytes)
}
}
#[derive(Zeroize, ZeroizeOnDrop)]
pub struct ClientRootKey {
master_key: [u8; DATA_PROTECTION_KEY_BYTES],
item_id_root: [u8; DATA_PROTECTION_KEY_BYTES],
value_root_key: [u8; DATA_PROTECTION_KEY_BYTES],
}
impl ClientRootKey {
pub fn from_bytes(bytes: [u8; DATA_PROTECTION_KEY_BYTES]) -> Self {
let item_id_root = blake3::derive_key(
crate::internal_core::contract::VALUE_FORMAT_ITEM_ID_ROOT_CONTEXT,
&bytes,
);
let value_root_key = blake3::derive_key(
crate::internal_core::contract::VALUE_FORMAT_VALUE_ROOT_CONTEXT,
&bytes,
);
Self {
master_key: bytes,
item_id_root,
value_root_key,
}
}
pub fn zero() -> Self {
Self::from_bytes([0; DATA_PROTECTION_KEY_BYTES])
}
pub fn public() -> Self {
Self::zero()
}
pub(crate) fn is_zero(&self) -> bool {
self.master_key.iter().all(|byte| *byte == 0)
}
pub fn from_slice(bytes: &[u8]) -> Result<Self> {
let exact: &[u8; DATA_PROTECTION_KEY_BYTES] = bytes.try_into().map_err(|_| {
Error::configuration(
"client_root_key",
format!(
"must contain exactly {DATA_PROTECTION_KEY_BYTES} bytes, got {}",
bytes.len()
),
)
})?;
Ok(Self::from_bytes(*exact))
}
pub fn from_base64(encoded: &str) -> Result<Self> {
let engine = if encoded.ends_with('=') {
&STANDARD
} else {
&STANDARD_NO_PAD
};
let decoded = Zeroizing::new(
engine
.decode(encoded)
.map_err(|error| Error::configuration("client_root_key", error.to_string()))?,
);
if decoded.len() != DATA_PROTECTION_KEY_BYTES {
return Err(Error::configuration(
"client_root_key",
format!(
"must decode to exactly {DATA_PROTECTION_KEY_BYTES} bytes, got {}",
decoded.len()
),
));
}
let mut bytes = [0; DATA_PROTECTION_KEY_BYTES];
bytes.copy_from_slice(&decoded);
Ok(Self::from_bytes(bytes))
}
pub fn to_base64(&self) -> String {
STANDARD.encode(self.master_key)
}
pub fn derive_item_id_in_namespace(
&self,
namespace_id: u64,
key: impl Into<TypedKey>,
) -> std::result::Result<ItemId, KeyError> {
self.derive_item_id_in_namespace_with_format(namespace_id, KeyFormat::NamespaceHash, key)
}
pub fn derive_item_id_in_namespace_with_format(
&self,
namespace_id: u64,
format: KeyFormat,
key: impl Into<TypedKey>,
) -> std::result::Result<ItemId, KeyError> {
let key = key.into();
if format == KeyFormat::ByteKeyOrHash {
let TypedKey::Bytes(bytes) = key else {
return Err(KeyError::InvalidFormatForKeyType {
format,
key_type: key.key_type(),
});
};
let key = ResolvedKey::from_direct_bytes(bytes)?;
return self.derive_item_id_for_resolved_key(namespace_id, format, &key);
}
let key = ResolvedKey::from_typed(key)?;
self.derive_item_id_for_resolved_key(namespace_id, format, &key)
}
pub fn derive_item_id_from_canonical_key(
&self,
namespace_id: u64,
canonical_key: &[u8],
) -> std::result::Result<ItemId, KeyError> {
self.derive_item_id_from_canonical_key_with_format(
namespace_id,
KeyFormat::NamespaceHash,
canonical_key,
)
}
pub fn derive_item_id_from_canonical_key_with_format(
&self,
namespace_id: u64,
format: KeyFormat,
canonical_key: &[u8],
) -> std::result::Result<ItemId, KeyError> {
let key = validate_canonical_key(canonical_key)?;
if format == KeyFormat::ByteKeyOrHash {
let typed = TypedKey::decode_canonical(key.bytes())?;
return self.derive_item_id_in_namespace_with_format(namespace_id, format, typed);
}
self.derive_item_id_from_validated_canonical_key(namespace_id, format, key)
}
pub(crate) fn derive_item_id_for_resolved_key(
&self,
namespace_id: u64,
format: KeyFormat,
key: &ResolvedKey,
) -> std::result::Result<ItemId, KeyError> {
if namespace_id == 0 {
return Err(KeyError::InvalidNamespace);
}
if format == KeyFormat::ByteKeyOrHash {
if let Some(direct) = key.legacy_direct.as_deref() {
return Ok(self.legacy_byte_key_or_hash(namespace_id, direct));
}
return Err(KeyError::InvalidFormatForKeyType {
format,
key_type: key.key_type(),
});
}
let canonical_key = key.canonical_bytes();
if format == KeyFormat::PublicKeyOrHash && canonical_key.len() <= MAX_ITEM_ID_BYTES {
return ItemId::from_slice(canonical_key).map_err(|_| KeyError::TooLarge {
size: canonical_key.len(),
maximum: MAX_ITEM_ID_BYTES,
});
}
if format == KeyFormat::PublicKeyOrHash {
return Ok(self.public_hash(canonical_key));
}
Ok(self.hash_canonical_key(namespace_id, format, canonical_key))
}
pub(crate) fn derive_item_id_from_validated_canonical_key(
&self,
namespace_id: u64,
format: KeyFormat,
key: ValidatedCanonicalKey<'_>,
) -> std::result::Result<ItemId, KeyError> {
if namespace_id == 0 {
return Err(KeyError::InvalidNamespace);
}
let canonical_key = key.bytes();
if format == KeyFormat::ByteKeyOrHash {
let typed = TypedKey::decode_canonical(canonical_key)?;
let TypedKey::Bytes(bytes) = typed else {
return Err(KeyError::InvalidFormatForKeyType {
format,
key_type: key.spec(),
});
};
return Ok(self.legacy_byte_key_or_hash(namespace_id, &bytes));
}
if format == KeyFormat::PublicKeyOrHash && canonical_key.len() <= MAX_ITEM_ID_BYTES {
return ItemId::from_slice(canonical_key).map_err(|_| KeyError::TooLarge {
size: canonical_key.len(),
maximum: MAX_ITEM_ID_BYTES,
});
}
if format == KeyFormat::PublicKeyOrHash {
return Ok(self.public_hash(canonical_key));
}
Ok(self.hash_canonical_key(namespace_id, format, canonical_key))
}
fn hash_canonical_key(
&self,
namespace_id: u64,
format: KeyFormat,
canonical_key: &[u8],
) -> ItemId {
let mut hasher = blake3::Hasher::new_keyed(&self.item_id_root);
if format == KeyFormat::NamespaceHash {
hasher.update(NAMESPACE_HASH_DOMAIN);
}
hasher.update(&namespace_id.to_be_bytes());
hasher.update(canonical_key);
ItemId::from_bytes(*hasher.finalize().as_bytes())
}
fn legacy_byte_key_or_hash(&self, namespace_id: u64, direct_key: &[u8]) -> ItemId {
if direct_key.len() <= MAX_ITEM_ID_BYTES {
return ItemId::from_slice(direct_key).expect("direct key length was validated");
}
let mut hasher = blake3::Hasher::new_keyed(&self.item_id_root);
hasher.update(&namespace_id.to_be_bytes());
hasher.update(direct_key);
ItemId::from_bytes(*hasher.finalize().as_bytes())
}
fn public_hash(&self, canonical_key: &[u8]) -> ItemId {
let mut hasher = blake3::Hasher::new();
hasher.update(PUBLIC_KEY_OR_HASH_DOMAIN);
hasher.update(canonical_key);
ItemId::from_bytes(*hasher.finalize().as_bytes())
}
pub fn derive_public_key_or_hash_in_namespace(
&self,
namespace_id: u64,
key: impl Into<TypedKey>,
) -> std::result::Result<ItemId, KeyError> {
let key = ResolvedKey::from_typed(key)?;
self.derive_item_id_for_resolved_key(namespace_id, KeyFormat::PublicKeyOrHash, &key)
}
#[deprecated(note = "use derive_item_id_in_namespace for v1 mapping")]
pub fn derive_legacy_hash_in_namespace(
&self,
namespace_id: u64,
key: impl Into<TypedKey>,
) -> std::result::Result<ItemId, KeyError> {
let key = ResolvedKey::from_typed(key)?;
self.derive_item_id_for_resolved_key(namespace_id, KeyFormat::Hash, &key)
}
#[deprecated(note = "use derive_public_key_or_hash_in_namespace for v1 mapping")]
pub fn derive_legacy_byte_key_or_hash_in_namespace(
&self,
namespace_id: u64,
direct_key: impl AsRef<[u8]>,
) -> std::result::Result<ItemId, KeyError> {
if namespace_id == 0 {
return Err(KeyError::InvalidNamespace);
}
let direct_key = direct_key.as_ref();
if direct_key.len() > MAX_KEY_INPUT_BYTES {
return Err(KeyError::TooLarge {
size: direct_key.len(),
maximum: MAX_KEY_INPUT_BYTES,
});
}
Ok(self.legacy_byte_key_or_hash(namespace_id, direct_key))
}
#[deprecated(note = "use derive_public_key_or_hash_in_namespace")]
pub fn derive_byte_key_or_hash_in_namespace(
&self,
namespace_id: u64,
direct_key: impl AsRef<[u8]>,
) -> std::result::Result<ItemId, KeyError> {
if namespace_id == 0 {
return Err(KeyError::InvalidNamespace);
}
let direct_key = direct_key.as_ref();
if direct_key.len() > MAX_KEY_INPUT_BYTES {
return Err(KeyError::TooLarge {
size: direct_key.len(),
maximum: MAX_KEY_INPUT_BYTES,
});
}
Ok(self.legacy_byte_key_or_hash(namespace_id, direct_key))
}
pub fn try_derive_item_id(
&self,
application_key: impl AsRef<[u8]>,
) -> std::result::Result<ItemId, KeyError> {
let key = ResolvedKey::from_typed(TypedKey::Bytes(application_key.as_ref().to_vec()))?;
self.derive_item_id_for_resolved_key(1, KeyFormat::Hash, &key)
}
pub fn derive_item_id(&self, application_key: impl AsRef<[u8]>) -> ItemId {
self.try_derive_item_id(application_key)
.expect("legacy application key exceeds the key input limit")
}
pub(crate) fn master_key(&self) -> Zeroizing<[u8; DATA_PROTECTION_KEY_BYTES]> {
Zeroizing::new(self.master_key)
}
}
pub type DataProtectionKey = ClientRootKey;
#[deprecated(note = "use KeyType")]
pub type KeySpec = KeyType;
#[deprecated(note = "use TypedInteger")]
pub type PortableInteger = TypedInteger;
#[deprecated(note = "use TypedKey")]
pub type PortableKey = TypedKey;
impl TryFrom<&[u8]> for ClientRootKey {
type Error = Error;
fn try_from(bytes: &[u8]) -> Result<Self> {
Self::from_slice(bytes)
}
}