kmwebnet/OpenSK
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

cbor: prepare for publishing as standalone crate

Browse Source 
- Add an example of usage
- Add a minimal README, including the example code
- Document public items
- Add more info to Cargo.toml
This commit is contained in:
David Drysdale
2021-06-09 10:12:55 +01:00
committed by kaczmarczyck
parent 7719078d46
commit 3aca5fbc74
7 changed files with 200 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
libraries/cbor/Cargo.toml
View File

@@ -5,8 +5,14 @@ authors = [
"Fabian Kaczmarczyck <kaczmarczyck@google.com>",
"Guillaume Endignoux <guillaumee@google.com>",
"Jean-Michel Picod <jmichel@google.com>",
"David Drysdale <drysdale@google.com>",
]
license = "Apache-2.0"
edition = "2018"
description = "CBOR parsing library"
homepage = "https://github.com/google/OpenSK"
repository = "https://github.com/google/OpenSK"
keywords = ["cbor", "serialization", "no_std"]
categories = ["encoding"]
[dependencies]

63
libraries/cbor/README.md Normal file
View File

@@ -0,0 +1,63 @@
# CBOR Parsing Library
This crate implements Concise Binary Object Representation (CBOR) from [RFC
8949](https://datatracker.ietf.org/doc/html/rfc8949).
## Usage
```rust
fn main() {
// Build a CBOR object with various different types included. Note that this
// object is not built in canonical order.
let manual_object = Value::Map(vec![
(
Value::Unsigned(1),
Value::Array(vec![Value::Unsigned(2), Value::Unsigned(3)]),
),
(
Value::TextString("tstr".to_owned()),
Value::ByteString(vec![1, 2, 3]),
),
(Value::Negative(-2), Value::Simple(SimpleValue::NullValue)),
(Value::Unsigned(3), Value::Simple(SimpleValue::TrueValue)),
]);
// Build the same object using the crate's convenience macros.
let macro_object = cbor_map! {
1 => cbor_array![2, 3],
"tstr" => cbor_bytes!(vec![1, 2, 3]),
-2 => cbor_null!(),
3 => cbor_true!(),
};
assert_eq!(manual_object, macro_object);
println!("Object {:?}", manual_object);
// Serialize to bytes.
let mut manual_data = vec![];
sk_cbor::writer::write(manual_object, &mut manual_data);
let hex_manual_data = hexify(&manual_data);
// Serialized version is in canonical order.
println!("Serializes to {}", hex_manual_data);
assert_eq!(
hex_manual_data,
concat!(
"a4", // 4-map
"01", // int(1) =>
"820203", // 2-array [2, 3],
"03", // int(3) =>
"f5", // true,
"21", // nint(-2) =>
"f6", // null,
"6474737472", // 4-tstr "tstr" =>
"43010203" // 3-bstr
)
);
// Convert back to an object. This is different than the original object,
// because the map is now in canonical order.
let recovered_object = sk_cbor::reader::read(&manual_data).unwrap();
println!("Deserializes to {:?}", recovered_object);
}
```

90
libraries/cbor/examples/cbor.rs Normal file
View File

@@ -0,0 +1,90 @@
// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
////////////////////////////////////////////////////////////////////////////////
//! Example program demonstrating cbor usage.
extern crate alloc;
use sk_cbor::values::{SimpleValue, Value};
use sk_cbor::{cbor_array, cbor_bytes, cbor_map, cbor_null, cbor_true};
fn hexify(data: &[u8]) -> String {
let mut s = String::new();
for b in data {
s.push_str(&format!("{:02x}", b));
}
s
}
fn main() {
// Build a CBOR object with various different types included. Note that this
// object is not built in canonical order.
let manual_object = Value::Map(vec![
(
Value::Unsigned(1),
Value::Array(vec![Value::Unsigned(2), Value::Unsigned(3)]),
),
(
Value::TextString("tstr".to_owned()),
Value::ByteString(vec![1, 2, 3]),
),
(Value::Negative(-2), Value::Simple(SimpleValue::NullValue)),
(Value::Unsigned(3), Value::Simple(SimpleValue::TrueValue)),
]);
// Build the same object using the crate's convenience macros.
let macro_object = cbor_map! {
1 => cbor_array![2, 3],
"tstr" => cbor_bytes!(vec![1, 2, 3]),
-2 => cbor_null!(),
3 => cbor_true!(),
};
assert_eq!(manual_object, macro_object);
println!("Object {:?}", manual_object);
// Serialize to bytes.
let mut manual_data = vec![];
sk_cbor::writer::write(manual_object, &mut manual_data);
let hex_manual_data = hexify(&manual_data);
let mut macro_data = vec![];
sk_cbor::writer::write(macro_object, &mut macro_data);
let hex_macro_data = hexify(&macro_data);
assert_eq!(hex_manual_data, hex_macro_data);
// Serialized version is in canonical order.
println!("Serializes to {}", hex_manual_data);
assert_eq!(
hex_manual_data,
concat!(
"a4", // 4-map
"01", // int(1) =>
"820203", // 2-array [2, 3],
"03", // int(3) =>
"f5", // true,
"21", // nint(-2) =>
"f6", // null,
"6474737472", // 4-tstr "tstr" =>
"43010203" // 3-bstr
)
);
// Convert back to an object. This is different than the original object,
// because the map is now in canonical order.
let recovered_object = sk_cbor::reader::read(&manual_data).unwrap();
println!("Deserializes to {:?}", recovered_object);
}

3
libraries/cbor/src/macros.rs
View File

@@ -12,6 +12,8 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//! Convenience macros for working with CBOR values.
use crate::values::Value;
use alloc::vec;
use core::cmp::Ordering;
@@ -110,6 +112,7 @@ pub fn destructure_cbor_map_peek_value(
}
}
/// Assert that the keys in a vector of key-value pairs are in canonical order.
#[macro_export]
macro_rules! assert_sorted_keys {
// Last key

5
libraries/cbor/src/reader.rs
View File

@@ -12,11 +12,14 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//! Functionality for deserializing CBOR data into values.
use super::values::{Constants, SimpleValue, Value};
use crate::{cbor_array_vec, cbor_bytes_lit, cbor_map_collection, cbor_text, cbor_unsigned};
use alloc::str;
use alloc::vec::Vec;
/// Possible errors from a deserialization operation.
#[derive(Debug, PartialEq)]
pub enum DecoderError {
UnsupportedMajorType,
@@ -32,6 +35,8 @@ pub enum DecoderError {
OutOfRangeIntegerValue,
}
/// Deserialize CBOR binary data to produce a single [`Value`], expecting that there
/// is no additional data.
pub fn read(encoded_cbor: &[u8]) -> Result<Value, DecoderError> {
let mut reader = Reader::new(encoded_cbor);
let value = reader.decode_complete_data_item(Reader::MAX_NESTING_DEPTH)?;

31
libraries/cbor/src/values.rs
View File

@@ -12,24 +12,34 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//! Types for expressing CBOR values.
use super::writer::write;
use alloc::string::{String, ToString};
use alloc::vec::Vec;
use core::cmp::Ordering;
/// Possible CBOR values.
#[derive(Clone, Debug)]
pub enum Value {
/// Unsigned integer value (uint).
Unsigned(u64),
// We only use 63 bits of information here.
/// Signed integer value (nint). Only 63 bits of information are used here.
Negative(i64),
/// Byte string (bstr).
ByteString(Vec<u8>),
/// Text string (tstr).
TextString(String),
/// Array/tuple of values.
Array(Vec<Value>),
/// Map of key-value pairs.
Map(Vec<(Value, Value)>),
// TAG is omitted
/// Simple value.
Simple(SimpleValue),
}
/// Specific simple CBOR values.
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub enum SimpleValue {
FalseValue = 20,
@@ -38,20 +48,30 @@ pub enum SimpleValue {
Undefined = 23,
}
/// Constant values required for CBOR encoding.
pub struct Constants {}
impl Constants {
/// Number of bits used to shift left the major type of a CBOR type byte.
pub const MAJOR_TYPE_BIT_SHIFT: u8 = 5;
/// Mask to retrieve the additional information held in a CBOR type bytes,
/// ignoring the major type.
pub const ADDITIONAL_INFORMATION_MASK: u8 = 0x1F;
/// Additional information value that indicates the largest inline value.
pub const ADDITIONAL_INFORMATION_MAX_INT: u8 = 23;
/// Additional information value indicating that a 1-byte length follows.
pub const ADDITIONAL_INFORMATION_1_BYTE: u8 = 24;
/// Additional information value indicating that a 2-byte length follows.
pub const ADDITIONAL_INFORMATION_2_BYTES: u8 = 25;
/// Additional information value indicating that a 4-byte length follows.
pub const ADDITIONAL_INFORMATION_4_BYTES: u8 = 26;
/// Additional information value indicating that an 8-byte length follows.
pub const ADDITIONAL_INFORMATION_8_BYTES: u8 = 27;
}
impl Value {
// For simplicity, this only takes i64. Construct directly for the last bit.
/// Create an appropriate CBOR integer value (uint/nint).
/// For simplicity, this only takes i64. Construct directly for the last bit.
pub fn integer(int: i64) -> Value {
if int >= 0 {
Value::Unsigned(int as u64)
@@ -60,6 +80,7 @@ impl Value {
}
}
/// Create a CBOR boolean simple value.
pub fn bool_value(b: bool) -> Value {
if b {
Value::Simple(SimpleValue::TrueValue)
@@ -68,6 +89,7 @@ impl Value {
}
}
/// Return the major type for the [`Value`].
pub fn type_label(&self) -> u8 {
// TODO use enum discriminant instead when stable
// https://github.com/rust-lang/rust/issues/60553
@@ -128,6 +150,7 @@ impl PartialEq for Value {
}
impl SimpleValue {
/// Create a simple value from its encoded value.
pub fn from_integer(int: u64) -> Option<SimpleValue> {
match int {
20 => Some(SimpleValue::FalseValue),
@@ -193,7 +216,9 @@ impl From<bool> for Value {
}
}
/// Trait that indicates that a type can be converted to a CBOR [`Value`].
pub trait IntoCborValue {
/// Convert `self` into a CBOR [`Value`], consuming it along the way.
fn into_cbor_value(self) -> Value;
}
@@ -206,7 +231,9 @@ where
}
}
/// Trait that indicates that a type can be converted to a CBOR [`Option<Value>`].
pub trait IntoCborValueOption {
/// Convert `self` into a CBOR [`Option<Value>`], consuming it along the way.
fn into_cbor_value_option(self) -> Option<Value>;
}

4
libraries/cbor/src/writer.rs
View File

@@ -12,9 +12,13 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//! Functionality for serializing CBOR values into bytes.
use super::values::{Constants, Value};
use alloc::vec::Vec;
/// Convert a [`Value`] to serialized CBOR data, consuming it along the way and appending to the provided vector.
/// Returns a `bool` indicating whether conversion succeeded.
pub fn write(value: Value, encoded_cbor: &mut Vec<u8>) -> bool {
let mut writer = Writer::new(encoded_cbor);
writer.encode_cbor(value, Writer::MAX_NESTING_DEPTH)