der-parser
BER/DER Parser
A parser for Basic Encoding Rules (BER [X.690]) and Distinguished Encoding Rules(DER [X.690]), implemented with the nom parser combinator framework.
The code is available on Github and is part of the Rusticata project.
DER parser design
There are two different approaches for parsing DER objects: reading the objects recursively as long as the tags are known, or specifying a description of the expected objects (generally from the ASN.1 description).
The first parsing method can be done using the parse_ber
and
parse_der
methods.
However, it cannot fully parse all objects, especially those containing IMPLICIT, OPTIONAL, or
DEFINED BY items.
use der_parser::parse_der;
let bytes = [ 0x30, 0x0a,
0x02, 0x03, 0x01, 0x00, 0x01,
0x02, 0x03, 0x01, 0x00, 0x00,
];
let parsed = parse_der(&bytes);
The second (and preferred) parsing method is to specify the expected objects recursively. The
following macros can be used:
parse_der_sequence_defined
and similar functions,
parse_der_struct
, etc.
For example, to read a sequence containing two integers:
use der_parser::ber::*;
use der_parser::error::BerResult;
fn localparse_seq(i:&[u8]) -> BerResult {
parse_der_sequence_defined!(i,
parse_ber_integer >>
parse_ber_integer
)
}
let bytes = [ 0x30, 0x0a,
0x02, 0x03, 0x01, 0x00, 0x01,
0x02, 0x03, 0x01, 0x00, 0x00,
];
let parsed = localparse_seq(&bytes);
All functions return a BerResult
object: the parsed
BerObject
, an Incomplete
value, or an error.
Note that this type is also a Result
, so usual functions (map
, unwrap
etc.) are available.
Notes
- The DER constraints are verified if using
parse_der
. BerObject
andDerObject
are the same objects (type alias). The only difference is the verification of constraints during parsing.- DER integers can be of any size, so it is not possible to store them as simple integers (they
are stored as raw bytes). To get a simple value, use
BerObject::as_u32
(knowning that this method will return an error if the integer is too large),BerObject::as_u64
, or use thebigint
feature of this crate and useBerObject::as_bigint
.
References
- [X.680] Abstract Syntax Notation One (ASN.1): Specification of basic notation.
- [X.690] ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER).
Changes
4.0.0
- Change the api around
Oid
to achieve zero-copy. The following changed:- The
Oid
struct now has a lifetime and usesCow
internally. - The
Oid
struct now encodes whether the oid is relative or not. Hash
is now derived forOid
.- The
Display
andDebug
implementation ofOid
now differs depending on whether thebignum
feature is activated. The reason is thatto_string
is now only available ifbignum
is activated. from_relative
was added toOid
.from
returns aResult
now.- The procedural macro
oid!
was added.
- The
- The string types
IA5String
,NumericString
,PrintableString
andUTF8String
do now only parse if the characters are valid. as_str()
was added toBerObjectContent
to obtain a&str
for the types above.as_slice()
works as before.
3.0.2
- Add
parse_ber_u32
andparse_ber_u64
functions - Fix typo in description
3.0.1
- Add crate
BerResult
andDerResult
types - Use crate result types, remove uneeded imports
- Crates using
der-parser
do not need to importnom
orrusticata-macros
anymore - Result types are aliases, so API is unchanged
- Crates using
3.0.0
- Upgrade to nom 5 (breaks API)
- New error types, now all functions use
BerError
2.1.0
- Handle BER/DER tags that are longer than one byte.
- Set edition to 2018
2.0.2
- Revert 2.0.1 release, breaks API
2.0.1
- Handle BER/DER tags that are longer than one byte.
2.0.0
- Refactor code, split BER and DER, check DER constraints
- Add recursion limit for sequences and sets
- Rustfmt
- Documentation
- Remove unused function
ber_read_element_content
1.1.1
- Fix OID parsing, and add support for relative OIDs
- Add FromStr trait for Oid
1.1.0
- Use num-bigint over num and upgrade to 0.2
1.0.0
- Upgrade to nom 4
0.5.5
- Add functions
parse_der_u32
andparse_der_u64
to quickly parse integers - Remove
Oid::from_vec
,Oid::from
does the same - Enforce constraints on DER booleans
0.5.4
- Add
BitStringObject
to wrap BitString objects - Mark constructed BitStrings as unsupported
- Do not try to parse application-specific data in
parse_der
0.5.3
- Add function
DerObject::as_u64
- Add function
DerObject::as_oid_val
- Add
parse_der_struct!
variant to check tag
0.5.2
- Add functions to test object class and primitive/constructed state
- Add macro
parse_der_application!
- Add macro
parse_der_tagged!
to parse[x] EXPLICIT
or[x] IMPLICIT
tagged values
0.5.1
- Add type GeneralString
- Add macro
parse_der_struct!
0.5.0
- Allow use of crate without extra use statements
- Use constants for u32 errors instead of magical numbers
- Rename
tag_of_der_content()
toDerObjectContent::tag
- Rename DerElementxxx structs to have a consistent naming scheme
- Add documentation for parsing DER sequences and sets, and fix wrong return type for sets
- Fix a lot of clippy warnings
- QA: add pragma rules (disable unsafe code, unstable features etc.)
- More documentation
- Switch license to MIT + APLv2
0.4.4
- Add macro parse_der_defined_m, to parse a defined sequence or set
This macro differs from
parse_der_defined
because it allows using macros - Rename
DerObject::new_int
toDerObject::from_int_slice
- Rename
Oid::to_hex
toOid::to_string
- Document more functions
0.4.1
- Add new feature 'bigint' to export DER integers
- OID is now a specific type
- Add new types T61String and BmpString
- Fix wrong expected tag in parse_der_set_of
0.4.0
- Der Integers are now represented as slices (byte arrays) since they can be larger than u64.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.