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 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354
|
# BER/DER Custom Derive Attributes
## BER/DER Sequence parsers
### `BER`
To derive a BER `SEQUENCE` parser, add the [`BerSequence`] derive attribute to an existing struct. Parsers will be derived automatically for all fields, which must implement the [`FromBer`] trait.
For ex:
```rust
# use asn1_rs::*;
#[derive(Debug, PartialEq, BerSequence)]
pub struct S {
a: u32,
b: u16,
c: u16,
}
# let parser = |input| -> Result<(), Error> {
let (rest, result) = S::from_ber(input)?;
# Ok(()) };
```
After parsing b, any bytes that were leftover and not used to fill val will be returned in `rest`.
When parsing a `SEQUENCE` into a struct, any trailing elements of the `SEQUENCE` that do
not have matching fields in val will not be included in `rest`, as these are considered
valid elements of the `SEQUENCE` and not trailing data.
### `DER`
To derive a `DER` parser, use the [`DerSequence`] custom attribute.
*Note: the `DerSequence` attributes derive both `BER` and `DER` parsers.*
## Tagged values
### `EXPLICIT`
There are several ways of parsing tagged values: either using types like [`TaggedExplicit`], or using custom annotations.
Using `TaggedExplicit` works as usual. The only drawback is that the type is visible in the structure, so accessing the value must be done using `.as_ref()` or `.into_inner()`:
```rust
# use asn1_rs::*;
#[derive(Debug, PartialEq, DerSequence)]
pub struct S2 {
a: u16,
}
// test with EXPLICIT Vec
#[derive(Debug, PartialEq, DerSequence)]
pub struct S {
// a INTEGER
a: u32,
// b INTEGER
b: u16,
// c [0] EXPLICIT SEQUENCE OF S2
c: TaggedExplicit<Vec<S2>, Error, 0>,
}
# let parser = |input| -> Result<(), Error> {
let (rem, result) = S::from_ber(input)?;
// Get a reference on c (type is &Vec<S2>)
let ref_c = result.c.as_ref();
# Ok(()) };
```
*Note: tags are context-specific by default. To specify other kind of tags (like `APPLICATION`) use [`TaggedValue`].*
### `tag_explicit`
To "hide" the tag from the parser, the `tag_explicit` attribute is provided. This attribute must specify the tag value (as an integer), and will automatically wrap reading the value with the specified tag.
```rust
# use asn1_rs::*;
#[derive(Debug, PartialEq, DerSequence)]
pub struct S {
// a [0] EXPLICIT INTEGER
#[tag_explicit(0)]
a: u16,
}
# let parser = |input| -> Result<(), Error> {
let (rem, result) = S::from_ber(input)?;
# Ok(()) };
```
This method handles transparently the encapsulation and the read of the tagged value.
*Note: tags are context-specific by default. To specify other kind of tags (like `APPLICATION`) add the tag class before the value in the `tag_explicit` attribute.*
For ex: `tag_explicit(APPLICATION 0)` or `tag_explicit(PRIVATE 2)`.
### Tagged optional values
The `optional` custom attribute can be used in addition of `tag_explicit` to specify that the value is `OPTIONAL`.
The type of the annotated field member must be resolvable to `Option`.
```rust
# use asn1_rs::*;
#[derive(Debug, PartialEq, DerSequence)]
pub struct S {
// a [0] EXPLICIT INTEGER OPTIONAL
#[tag_explicit(0)]
#[optional]
a: Option<u16>,
// b INTEGER
b: u16,
}
# let parser = |input| -> Result<(), Error> {
let (rem, result) = S::from_ber(input)?;
# Ok(()) };
```
### `IMPLICIT`
Tagged `IMPLICIT` values are handled similarly as for `EXPLICIT`, and can be parsed either using the [`TaggedImplicit`] type, or using the `tag_implicit` custom attribute.
For ex:
```rust
# use asn1_rs::*;
#[derive(Debug, PartialEq, DerSequence)]
pub struct S {
// a [0] IMPLICIT INTEGER OPTIONAL
#[tag_implicit(0)]
#[optional]
a: Option<u16>,
// b INTEGER
b: u16,
}
# let parser = |input| -> Result<(), Error> {
let (rem, result) = S::from_ber(input)?;
# Ok(()) };
```
## `OPTIONAL` values (not tagged)
The `optional` custom attribute can be specified to indicate the value is `OPTIONAL`.
```rust
# use asn1_rs::*;
#[derive(Debug, PartialEq, DerSequence)]
pub struct S {
// a INTEGER
a: u16,
// b INTEGER OPTIONAL
#[optional]
b: Option<u16>,
}
# let parser = |input| -> Result<(), Error> {
let (rem, result) = S::from_ber(input)?;
# Ok(()) };
```
**Important**: there are several limitations to this attribute.
In particular, the parser is eager: when an `OPTIONAL` value of some type is followed by another value (not `OPTIONAL`) of the same type, this can create problem.
If only one value is present, the parser will affect it to the first field, and then raise an error because the second is absent.
Note that this does not concern tagged optional values (unless they have the same tag).
## `DEFAULT`
The `default` custom attribute can be specified to indicate the value has a `DEFAULT` attribute. The value can also be marked as
`OPTIONAL`, but this can be omitted.
Since the value can always be obtained, the type should not be `Option<T>`, but should use `T` directly.
```rust
# use asn1_rs::*;
#[derive(Debug, PartialEq, DerSequence)]
#[debug_derive]
pub struct S {
// a INTEGER
a: u16,
// b INTEGER DEFAULT 0
#[default(0_u16)]
b: u16,
}
# let parser = |input| -> Result<(), Error> {
let (rem, result) = S::from_ber(input)?;
# Ok(()) };
```
Limitations are the same as for `OPTIONAL` attribute.
## Debugging
To help debugging the generated code, the `#[debug_derive]` attribute has been added.
When this attribute is specified, the generated code will be printed to `stderr` during compilation.
Example:
```rust
use asn1_rs::*;
#[derive(BerSequence)]
#[debug_derive]
struct S {
a: u32,
}
```
## BER/DER Set parsers
Parsing BER/DER `SET` objects is very similar to `SEQUENCE`. Use the [`BerSet`] and [`DerSet`] custom derive attributes on the structure, and everything else is exactly the same as for sequences (see above for documentation).
Example:
```rust
# use asn1_rs::*;
use std::collections::BTreeSet;
// `Ord` is needed because we will parse as a `BTreeSet` later
#[derive(Debug, DerSet, PartialEq, Eq, PartialOrd, Ord)]
pub struct S2 {
a: u16,
}
// test with EXPLICIT Vec
#[derive(Debug, PartialEq, DerSet)]
pub struct S {
// a INTEGER
a: u32,
// b INTEGER
b: u16,
// c [0] EXPLICIT SET OF S2
c: TaggedExplicit<BTreeSet<S2>, Error, 0>,
}
# let parser = |input| -> Result<(), Error> {
let (rem, result) = S::from_ber(input)?;
// Get a reference on c (type is &BTreeSet<S2>)
let ref_c = result.c.as_ref();
# Ok(()) };
```
# Advanced
## Custom errors
Derived parsers can use the `error` attribute to specify the error type of the parser.
The custom error type must implement `From<Error>`, so the derived parsers will transparently convert errors using the [`Into`] trait.
Example:
```rust
# use asn1_rs::*;
#
#[derive(Debug, PartialEq)]
pub enum MyError {
NotYetImplemented,
}
impl From<asn1_rs::Error> for MyError {
fn from(_: asn1_rs::Error) -> Self {
MyError::NotYetImplemented
}
}
#[derive(DerSequence)]
#[error(MyError)]
pub struct T2 {
pub a: u32,
}
```
## Mapping errors
Sometimes, it is necessary to map the returned error to another type, for example when a subparser returns a different error type than the parser's, and the [`Into`] trait cannot be implemented. This is often used in combination with the `error` attribute, but can also be used alone.
The `map_err` attribute can be used to specify a function or closure to map errors. The function signature is `fn (e1: E1) -> E2`.
Example:
```rust
# use asn1_rs::*;
#
#[derive(Debug, PartialEq)]
pub enum MyError {
NotYetImplemented,
}
impl From<asn1_rs::Error> for MyError {
fn from(_: asn1_rs::Error) -> Self {
MyError::NotYetImplemented
}
}
#[derive(DerSequence)]
#[error(MyError)]
pub struct T2 {
pub a: u32,
}
// subparser returns an error of type MyError,
// which is mapped to `Error`
#[derive(DerSequence)]
pub struct T4 {
#[map_err(|_| Error::BerTypeError)]
pub a: T2,
}
```
*Note*: when deriving BER and DER parsers, errors paths are different (`TryFrom` returns the error type, while [`FromDer`] returns a [`ParseResult`]). Some code will be inserted by the `map_err` attribute to handle this transparently and keep the same function signature.
# Serialization
## BER/DER Sequence serialization
To serialize a struct to a DER `SEQUENCE`, add the [`ToDerSequence`] derive attribute to an existing struct.
Serialization will be derived automatically for all fields, which must implement the [`ToDer`] trait.
Some parser traits may be required, so also deriving parsers using [`DerSequence`] may be required.
*Note*: serialization to BER is currently not available. In most cases, DER serialization should be enough.
For ex:
```rust
# use asn1_rs::*;
#[derive(Debug, PartialEq, DerSequence, ToDerSequence)]
pub struct S {
a: u32,
b: u16,
c: u16,
}
let s = S { a: 1, b: 2, c: 3 };
let output = s.to_der_vec().expect("serialization failed");
let (_rest, result) = S::from_ber(&output).expect("parsing failed");
assert_eq!(s, result);
```
[`FromBer`]: crate::FromBer
[`FromDer`]: crate::FromDer
[`ToDer`]: crate::ToDer
[`BerSequence`]: crate::BerSequence
[`DerSequence`]: crate::DerSequence
[`BerSet`]: crate::BerSet
[`DerSet`]: crate::DerSet
[`ToDerSequence`]: crate::ToDerSequence
[`ParseResult`]: crate::ParseResult
[`TaggedExplicit`]: crate::TaggedExplicit
[`TaggedImplicit`]: crate::TaggedImplicit
[`TaggedValue`]: crate::TaggedValue
|