Expand description
BER/DER Parsers/Encoders
A set of parsers/encoders for Basic Encoding Rules (BER [X.690]) and Distinguished Encoding Rules(DER [X.690]) formats, implemented with the nom parser combinator framework.
It is written in pure Rust, fast, and makes extensive use of zero-copy. A lot of care is taken to ensure security and safety of this crate, including design (recursion limit, defensive programming), tests, and fuzzing. It also aims to be panic-free.
This crate is a rewrite of der-parser to propose a more data-oriented API, and add generalized support for serialization.
Many ideas were borrowed from the crypto/utils/der crate (like
the Any
/TryFrom
/FromDer
mechanism), adapted and merged into a generalized BER/DER crate.
Credits (and many thanks) go to Tony Arcieri for writing the original crate.
BER/DER parsers
BER stands for Basic Encoding Rules, and is defined in [X.690]. It defines a set of rules to encode and decode ASN.1 [X.680] objects in binary.
[X.690] also defines Distinguished Encoding Rules (DER), which is BER with added rules to ensure canonical and unequivocal binary representation of objects.
The choice of which one to use is usually guided by the speficication of the data format based on BER or DER: for example, X.509 uses DER as encoding representation.
The main traits for parsing are the FromBer
and FromDer
traits.
These traits provide methods to parse binary input, and return either the remaining (unparsed) bytes
and the parsed object, or an error.
The parsers follow the interface from nom, and the ParseResult
object is a specialized version
of nom::IResult
. This means that most nom
combinators (map
, many0
, etc.) can be used in
combination to objects and methods from this crate. Reading the nom documentation may
help understanding how to write and combine parsers and use the output.
Minimum Supported Rust Version: 1.53.0
Note: if the bits
feature is enabled, MSRV is 1.56.0 (due to bitvec
1.0)
Recipes
See doc::recipes and doc::derive for more examples and recipes.
Examples
Parse 2 BER integers:
use asn1_rs::{Integer, FromBer};
let bytes = [ 0x02, 0x03, 0x01, 0x00, 0x01,
0x02, 0x03, 0x01, 0x00, 0x00,
];
let (rem, obj1) = Integer::from_ber(&bytes).expect("parsing failed");
let (rem, obj2) = Integer::from_ber(&bytes).expect("parsing failed");
assert_eq!(obj1, Integer::from_u32(65537));
In the above example, the generic Integer
type is used. This type can contain integers of any
size, but do not provide a simple API to manipulate the numbers.
In most cases, the integer either has a limit, or is expected to fit into a primitive type.
To get a simple value, just use the from_ber
/from_der
methods on the primitive types:
use asn1_rs::FromBer;
let bytes = [ 0x02, 0x03, 0x01, 0x00, 0x01,
0x02, 0x03, 0x01, 0x00, 0x00,
];
let (rem, obj1) = u32::from_ber(&bytes).expect("parsing failed");
let (rem, obj2) = u32::from_ber(&rem).expect("parsing failed");
assert_eq!(obj1, 65537);
assert_eq!(obj2, 65536);
If the parsing succeeds, but the integer cannot fit into the expected type, the method will return
an IntegerTooLarge
error.
BER/DER encoders
BER/DER encoding is symmetrical to decoding, using the traits ToBer
and ToDer
traits.
These traits provide methods to write encoded content to objects with the io::Write
trait,
or return an allocated Vec<u8>
with the encoded data.
If the serialization fails, an error is returned.
Examples
Writing 2 BER integers:
use asn1_rs::{Integer, ToDer};
let mut writer = Vec::new();
let obj1 = Integer::from_u32(65537);
let obj2 = Integer::from_u32(65536);
let _ = obj1.write_der(&mut writer).expect("serialization failed");
let _ = obj2.write_der(&mut writer).expect("serialization failed");
let bytes = &[ 0x02, 0x03, 0x01, 0x00, 0x01,
0x02, 0x03, 0x01, 0x00, 0x00,
];
assert_eq!(&writer, bytes);
Similarly to FromBer
/FromDer
, serialization methods are also implemented for primitive types:
use asn1_rs::ToDer;
let mut writer = Vec::new();
let _ = 65537.write_der(&mut writer).expect("serialization failed");
let _ = 65536.write_der(&mut writer).expect("serialization failed");
let bytes = &[ 0x02, 0x03, 0x01, 0x00, 0x01,
0x02, 0x03, 0x01, 0x00, 0x00,
];
assert_eq!(&writer, bytes);
If the parsing succeeds, but the integer cannot fit into the expected type, the method will return
an IntegerTooLarge
error.
Changes
See CHANGELOG.md
.
References
Re-exports
pub use nom;
Modules
Additional documentation: recipes, specific use cases and examples, etc.
Macros
Helper macro to declare integers at compile-time
Helper macro to declare integers at compile-time
Structs
The Any
object is not strictly an ASN.1 type, but holds a generic description of any object
that could be encoded.
ASN.1 BITSTRING
type
ASN.1 BMPSTRING
type
ASN.1 BOOLEAN
type
End-of-contents octets
ASN.1 ENUMERATED
type
ASN.1 restricted character string type (GeneralString
)
ASN.1 restricted character string type (GraphicString
)
BER/DER object header (identifier and length)
ASN.1 restricted character string type (Ia5String
)
ASN.1 INTEGER
type
ASN.1 NULL
type
ASN.1 restricted character string type (NumericString
)
ASN.1 restricted character string type (ObjectDescriptor
)
ASN.1 OCTETSTRING
type
Object ID (OID) representation which can be relative or non-relative.
An example for an OID in string representation is "1.2.840.113549.1.1.5"
.
Helper object to parse TAGGED OPTIONAL types (explicit or implicit)
ASN.1 restricted character string type (PrintableString
)
The SEQUENCE
object is an ordered list of heteregeneous types.
An Iterator over binary data, parsing elements of type T
The SEQUENCE OF
object is an ordered list of homogeneous types.
The SET
object is an unordered list of heteregeneous types.
The SET OF
object is an unordered list of homogeneous types.
BER/DER Tag as defined in X.680 section 8.4
A builder for parsing tagged values (IMPLICIT
or EXPLICIT
)
Helper object for creating FromBer
/FromDer
types for TAGGED OPTIONAL types
ASN.1 restricted character string type (TeletexString
)
ASN.1 UniversalString
type
ASN.1 restricted character string type (Utf8String
)
ASN.1 restricted character string type (VideotexString
)
ASN.1 restricted character string type (VisibleString
)
Enums
BER Object class of tag
Error types for DER constraints
The Err
enum indicates the parser was not successful
A type parameter for EXPLICIT
tagged values.
A type parameter for IMPLICIT
tagged values.
BER Object Length
Contains information on needed data if a parser returned Incomplete
An error for OID parsing functions.
ASN.1 REAL
type
The error type for serialization operations of the ToDer
trait.
Traits
Helper trait for creating tagged EXPLICIT values
Helper trait for creating tagged IMPLICIT values
Verification of DER constraints
Trait to automatically derive FromDer
Base trait for BER object parsers
Base trait for DER object parsers
Base trait for BER string objects and character set validation
Common trait for all objects that can be encoded using the DER representation
Functions
Type Definitions
A helper object to parse [APPLICATION n] EXPLICIT T
A helper object to parse [APPLICATION n] IMPLICIT T
Holds the result of parsing functions
A helper object to parse [ n ] EXPLICIT T OPTIONAL
A helper object to parse [ n ] IMPLICIT T OPTIONAL
Holds the result of BER/DER serialization functions
A helper object to parse [PRIVATE n] EXPLICIT T
A helper object to parse [PRIVATE n] IMPLICIT T
A specialized Result
type for all operations from this crate.
Holds the result of BER/DER encoding functions
An Iterator over binary data, parsing elements of type T
A helper object to parse [ n ] EXPLICIT T
A helper object to parse [ n ] IMPLICIT T
Derive Macros
BerAlias custom derive
BerSequence custom derive
BerSet custom derive
DerAlias custom derive
DerSequence custom derive
DerSet custom derive