Crate der_derive

Crate der_derive 

Source
Expand description

§RustCrypto: DER Custom Derive Support

crate Docs Build Status Apache2/MIT licensed Rust Version Project Chat

Custom derive support for the der crate’s Choice and Sequence traits:

https://github.com/RustCrypto/formats/tree/master/der

Documentation

§Minimum Supported Rust Version

This crate requires Rust 1.65 at a minimum.

We may change the MSRV in the future, but it will be accompanied by a minor version bump.

§License

Licensed under either of:

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.

§About

Custom derive support for the der crate.

This crate contains custom derive macros intended to be used in the following way:

  • Choice: map ASN.1 CHOICE to a Rust enum.
  • Enumerated: map ASN.1 ENUMERATED to a C-like Rust enum.
  • Sequence: map ASN.1 SEQUENCE to a Rust struct.
  • ValueOrd: determine DER ordering for ASN.1 SET OF.

Note that this crate shouldn’t be used directly, but instead accessed by using the derive feature of the der crate, which re-exports the above macros from the toplevel.

§Why not serde?

The der crate is designed to be easily usable in embedded environments, including ones where code size comes at a premium.

This crate (i.e. der_derive) is able to generate code which is significantly smaller than serde_derive. This is because the der crate has been designed with high-level abstractions which reduce code size, including trait object-based encoders which allow encoding logic which is duplicated in serde serializers to be implemented in a single place in the der crate.

This is a deliberate tradeoff in terms of performance, flexibility, and code size. At least for now, the der crate is optimizing for leveraging as many abstractions as it can to minimize code size.

§Toplevel attributes

The following attributes can be added to an enum or struct when deriving either Choice or Sequence respectively:

§#[asn1(tag_mode = "...")] attribute: EXPLICIT vs IMPLICIT

This attribute can be used to declare the tagging mode used by a particular ASN.1 module.

It’s used when parsing CONTEXT-SENSITIVE fields.

The default is EXPLICIT, so the attribute only needs to be added when a particular module is declared IMPLICIT.

§Field-level attributes

The following attributes can be added to either the fields of a particular struct or the variants of a particular enum:

§#[asn1(context_specific = "...")] attribute: CONTEXT-SPECIFIC support

This attribute can be added to associate a particular CONTEXT-SPECIFIC tag number with a given enum variant or struct field.

The value must be quoted and contain a number, e.g. #[asn1(context_specific = "29")].

§#[asn1(default = "...")] attribute: DEFAULT support

This behaves like serde_derive’s default attribute, allowing you to specify the path to a function which returns a default value.

§#[asn1(extensible = "true")] attribute: support for ... extensibility operator

This attribute can be applied to the fields of struct types, and will skip over unrecognized lower-numbered CONTEXT-SPECIFIC fields when looking for a particular field of a struct.

§#[asn1(optional = "true")] attribute: support for OPTIONAL fields

This attribute explicitly annotates a field as OPTIONAL.

§#[asn1(type = "...")] attribute: ASN.1 type declaration

This attribute can be used to specify the ASN.1 type for a particular enum variant or struct field.

It’s presently mandatory for all enum variants, even when using one of the ASN.1 types defined by this crate.

For structs, placing this attribute on a field makes it possible to decode/encode types which don’t directly implement the Decode/Encode traits but do impl From and TryInto and From for one of the ASN.1 types listed below (use the ASN.1 type keywords as the type):

§#[asn1(constructed = "...")] attribute: support for constructed inner types

This attribute can be used to specify that an “inner” type is constructed. It is most commonly used when a CHOICE has a constructed inner type.

Note: please open a GitHub Issue if you would like to request support for additional ASN.1 types.

Derive Macros§

Choice
Derive the Choice trait on an enum.
Enumerated
Derive decoders and encoders for ASN.1 Enumerated types on a C-like enum type.
Sequence
Derive the Sequence trait on a struct.
ValueOrd
Derive the ValueOrd trait on a struct.