• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1## Upgrading from 4.x to 5.0
2
3### BER variants: ContextSpecific, Optional, Tagged
4
5The variant `ContextSpecific` has been removed from `BerObject`, and 2 new variants have been added:
6- `Tagged` for explicit tagged objects,
7- `Optional` to simplify writing subparsers with only `BerObject`
8
9This is also used to clarify parsing of tagged values, and the API now clearly says if trying to parse an
10optional value or not.
11
12### Ber Size
13
14The `len` field of `BerObjectHeader` is now an enum, to represent definite and indefinite lengths.
15To get the value, either match the type, or use `try_from` (which will fail if indefinite).
16
17### Struct parsing Macros
18
19Functions and combinators are now the preferred way of parsing constructed objects.
20
21Macros have been upgrading and use the combinators internally. As a consequence, they do not return
22a tuple `(BerObjectHeader, T)` but only the built object `T`. The header should be removed from function
23signatures, for ex:
24```
25-fn parse_struct01(i: &[u8]) -> BerResult<(BerObjectHeader,MyStruct)> {
26+fn parse_struct01(i: &[u8]) -> BerResult<MyStruct> {
27```
28
29The header was usually ignored, so this should simplify most uses of this macro. To get the header,
30use `parse_ber_container` directly.
31
32## Upgrading from 3.x to 4.0
33
34### Ber Object and Header
35
36The `class`, `structured` and `tag` fields were duplicated in `BerObject` and the header.
37Now, a header is always created and embedded in the BER object, with the following changes:
38
39- To access these fields, use the header: `obj.tag` becomes `obj.header.tag`, etc.
40- `BerObject::to_header()` is now deprecated
41- The `len` field is now public. However, in some cases it can be 0 (when creating an object, 0 means that serialization will calculate the length)
42- As a consequence, `PartialEq` on BER objects and headers compare `len` only if set in both objects
43
44### BER String types verification
45
46Some BER String types (`IA5String`, `NumericString`, `PrintableString` and `UTF8String`) are now
47verified, and will now only parse if the characters are valid.
48
49Their types have change from slice to `str` in the `BerObjectContent` enum.
50
51### BerClass
52
53The `class` field of `BerObject` struct now uses the newtype `BerClass`. Use the provided constants
54(for ex `BerClass:Universal`). To access the value, just use `class.0`.
55
56### Maximum depth
57
58The `depth` argument of functions (for ex. `ber_read_element_content_as`) has changed, and is now the maximum possible depth while parsing.
59Change it (usually from `0`) to a possible limit, for ex `der_parser::ber::MAX_RECURSION`.
60
61### Oid
62
63This is probably the most impacting change.
64
65OID objects have been refactored, and are now zero-copy. This has several consequences:
66
67- `Oid` struct now has a lifetime, which must be propagated to objects using them
68  - This makes having globally static structs difficult. Obtaining a `'static` object is possible
69    using the `oid` macro. For ex:
70
71```rust
72const SOME_STATIC_OID: Oid<'static> = oid!(1.2.456);
73```
74
75- Due to limitations of procedural macros  ([rust
76  issue](https://github.com/rust-lang/rust/issues/54727)) and constants used in patterns ([rust issue](https://github.com/rust-lang/rust/issues/31434)), the `oid` macro can not directly be used in patterns, also not through constants.
77You can do this, though:
78
79```rust
80# use der_parser::{oid, oid::Oid};
81# let some_oid: Oid<'static> = oid!(1.2.456);
82const SOME_OID: Oid<'static> = oid!(1.2.456);
83if some_oid == SOME_OID || some_oid == oid!(1.2.456) {
84    println!("match");
85}
86
87// Alternatively, compare the DER encoded form directly:
88const SOME_OID_RAW: &[u8] = &oid!(raw 1.2.456);
89match some_oid.bytes() {
90    SOME_OID_RAW => println!("match"),
91    _ => panic!("no match"),
92}
93```
94*Attention*, be aware that the latter version might not handle the case of a relative oid correctly. An
95extra check might be necessary.
96
97- To build an `Oid`, the `from`, `new` or `new_relative` methods can be used.
98- The `from` method now returns a `Result` (failure can happen if the first components are too
99  large, for ex)
100- An `oid` macro has also been added in the `der-oid-macro` crate to easily build an `Oid` (see
101  above).
102