facet-asn1 0.43.1

ASN.1 DER/BER serialization and deserialization for facet
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! ASN.1 DER/BER serialization and deserialization for facet.
//!
//! This crate provides ASN.1 DER (Distinguished Encoding Rules) support via the
//! `FormatParser` and `FormatSerializer` traits.
//!
//! # ASN.1 Overview
//!
//! ASN.1 (Abstract Syntax Notation One) is a standard interface description language
//! for defining data structures that can be serialized and deserialized in a
//! cross-platform way. DER is a specific encoding rule that ensures canonical encoding.
//!
//! # Serialization
//!
//! ```
//! use facet::Facet;
//! use facet_asn1::to_vec;
//!
//! #[derive(Facet)]
//! struct Point { x: i32, y: i32 }
//!
//! let point = Point { x: 10, y: 20 };
//! let bytes = to_vec(&point).unwrap();
//! ```
//!
//! # Deserialization
//!
//! ```ignore
//! use facet::Facet;
//! use facet_asn1::from_slice;
//!
//! #[derive(Facet)]
//! struct Point { x: i32, y: i32 }
//!
//! // DER encoding of Point { x: 10, y: 20 }
//! let bytes = &[0x30, 0x06, 0x02, 0x01, 0x0A, 0x02, 0x01, 0x14];
//! let point: Point = from_slice(bytes).unwrap();
//! ```
//!
//! # Type Mapping
//!
//! | Rust Type | ASN.1 Type |
//! |-----------|------------|
//! | `bool` | BOOLEAN |
//! | `i8`, `i16`, `i32`, `i64` | INTEGER |
//! | `u8`, `u16`, `u32`, `u64` | INTEGER |
//! | `f32`, `f64` | REAL |
//! | `String`, `&str` | UTF8String |
//! | `Vec<u8>`, `&[u8]` | OCTET STRING |
//! | struct | SEQUENCE |
//! | `Vec<T>` | SEQUENCE OF |
//! | `Option<T>` | Optional field |
//! | `()` | NULL |

#![cfg_attr(not(feature = "std"), no_std)]

extern crate alloc;

mod error;
mod parser;
mod serializer;

pub use error::{Asn1Error, Asn1ErrorKind};
pub use parser::Asn1Parser;
pub use serializer::{Asn1SerializeError, Asn1Serializer, to_vec};

// Re-export DeserializeError for convenience
pub use facet_format::DeserializeError;

/// Deserialize a value from ASN.1 DER bytes into an owned type.
///
/// This is the recommended default for most use cases. The input does not need
/// to outlive the result, making it suitable for deserializing from temporary
/// buffers.
///
/// # Example
///
/// ```ignore
/// use facet::Facet;
/// use facet_asn1::from_slice;
///
/// #[derive(Facet, Debug, PartialEq)]
/// struct Point {
///     x: i32,
///     y: i32,
/// }
///
/// // DER encoding of Point { x: 10, y: 20 }
/// let bytes = &[0x30, 0x06, 0x02, 0x01, 0x0A, 0x02, 0x01, 0x14];
/// let point: Point = from_slice(bytes).unwrap();
/// assert_eq!(point.x, 10);
/// assert_eq!(point.y, 20);
/// ```
pub fn from_slice<T>(input: &[u8]) -> Result<T, DeserializeError<Asn1Error>>
where
    T: facet_core::Facet<'static>,
{
    use facet_format::FormatDeserializer;
    let parser = Asn1Parser::new(input);
    let mut de = FormatDeserializer::new_owned(parser);
    de.deserialize()
}

/// Deserialize a value from ASN.1 DER bytes, allowing zero-copy borrowing.
///
/// This variant requires the input to outlive the result (`'input: 'facet`),
/// enabling zero-copy deserialization of byte slices as `&[u8]` or `Cow<[u8]>`.
///
/// Use this when you need maximum performance and can guarantee the input
/// buffer outlives the deserialized value.
pub fn from_slice_borrowed<'input, 'facet, T>(
    input: &'input [u8],
) -> Result<T, DeserializeError<Asn1Error>>
where
    T: facet_core::Facet<'facet>,
    'input: 'facet,
{
    use facet_format::FormatDeserializer;
    let parser = Asn1Parser::new(input);
    let mut de = FormatDeserializer::new(parser);
    de.deserialize()
}