Crate asn1_rs

Available on crate feature mtls only.

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.63.0

§Recipes

See [doc::recipes] and [doc::derive] for more examples and recipes.

See [doc::debug] for advice and tools to debug parsers.

§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

[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).

Modules§

nom: nom, eating data byte by byte

Macros§

int: Helper macro to declare integers at compile-time
oid: Helper macro to declare integers at compile-time

Structs§

ASN1DateTime
Any: The Any object is not strictly an ASN.1 type, but holds a generic description of any object that could be encoded.
BerClassFromIntError
BitString: ASN.1 BITSTRING type
BmpString: ASN.1 BMPSTRING type
Boolean: ASN.1 BOOLEAN type
EmbeddedPdv
EndOfContent: End-of-contents octets
Enumerated: ASN.1 ENUMERATED type
GeneralString: ASN.1 restricted character string type (GeneralString)
GeneralizedTime
GraphicString: ASN.1 restricted character string type (GraphicString)
Header: BER/DER object header (identifier and length)
Ia5String: ASN.1 restricted character string type (Ia5String)
Integer: ASN.1 INTEGER type
Null: ASN.1 NULL type
NumericString: ASN.1 restricted character string type (NumericString)
ObjectDescriptor: ASN.1 restricted character string type (ObjectDescriptor)
OctetString: ASN.1 OCTETSTRING type
Oid: 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".
OptTaggedParser: Helper object to parse TAGGED OPTIONAL types (explicit or implicit)
PrintableString: ASN.1 restricted character string type (PrintableString)
Sequence: The SEQUENCE object is an ordered list of heteregeneous types.
SequenceIterator: An Iterator over binary data, parsing elements of type T
SequenceOf: The SEQUENCE OF object is an ordered list of homogeneous types.
Set: The SET object is an unordered list of heteregeneous types.
SetOf: The SET OF object is an unordered list of homogeneous types.
Tag: BER/DER Tag as defined in X.680 section 8.4
TaggedParser
TaggedParserBuilder: A builder for parsing tagged values (IMPLICIT or EXPLICIT)
TaggedValue: Helper object for creating FromBer/FromDer types for TAGGED OPTIONAL types
TeletexString: ASN.1 restricted character string type (TeletexString)
UniversalString: ASN.1 UniversalString type
UtcTime
Utf8String: ASN.1 restricted character string type (Utf8String)
VideotexString: ASN.1 restricted character string type (VideotexString)
VisibleString: ASN.1 restricted character string type (VisibleString)

Enums§

ASN1TimeZone
Class: BER Object class of tag
DerConstraint: Error types for DER constraints
Err: The Err enum indicates the parser was not successful
Error: The error type for operations of the FromBer, FromDer, and associated traits.
Explicit: A type parameter for EXPLICIT tagged values.
Implicit: A type parameter for IMPLICIT tagged values.
Length: BER Object Length
Needed: Contains information on needed data if a parser returned Incomplete
OidParseError: An error for OID parsing functions.
PdvIdentification
Real: ASN.1 REAL type
SerializeError: The error type for serialization operations of the ToDer trait.

Traits§

AsTaggedExplicit: Helper trait for creating tagged EXPLICIT values
AsTaggedImplicit: Helper trait for creating tagged IMPLICIT values
BerChoice
CheckDerConstraints: Verification of DER constraints
Choice
DerAutoDerive: Trait to automatically derive FromDer
DerChoice
DynTagged
FromBer: Base trait for BER object parsers
FromDer: Base trait for DER object parsers
TagKind: A type parameter for tagged values either Explicit or Implicit.
Tagged
TestValidCharset: Base trait for BER string objects and character set validation
ToDer: Common trait for all objects that can be encoded using the DER representation
ToStatic

Functions§

from_nom_error: Flatten all nom::Err variants error into a single error type
parse_der_tagged_explicit
parse_der_tagged_explicit_g
parse_der_tagged_implicit
parse_der_tagged_implicit_g

Type Aliases§

ApplicationExplicit: A helper object to parse [APPLICATION n] EXPLICIT T
ApplicationImplicit: A helper object to parse [APPLICATION n] IMPLICIT T
IResult: Holds the result of parsing functions
OptTaggedExplicit: A helper object to parse [ n ] EXPLICIT T OPTIONAL
OptTaggedImplicit: A helper object to parse [ n ] IMPLICIT T OPTIONAL
ParseResult: Holds the result of BER/DER serialization functions
PrivateExplicit: A helper object to parse [PRIVATE n] EXPLICIT T
PrivateImplicit: A helper object to parse [PRIVATE n] IMPLICIT T
Result: A specialized Result type for all operations from this crate.
SerializeResult: Holds the result of BER/DER encoding functions
SetIterator: An Iterator over binary data, parsing elements of type T
TaggedExplicit: A helper object to parse [ n ] EXPLICIT T
TaggedImplicit: A helper object to parse [ n ] IMPLICIT T

Derive Macros§

BerAlias
BerSequence
BerSet
DerAlias
DerSequence
DerSet

Crate asn1_rs

Crate asn1_rs Copy item path

§BER/DER Parsers/Encoders

§BER/DER parsers

§Recipes

§Examples

§BER/DER encoders

§Examples

§Changes

§References

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Derive Macros§

Crate asn1_rs