Crate wildboar_asn1

Expand description

§Abstract Syntax Notation 1 (ASN.1) Library

This crate contains types and functions for using ASN.1 values. This library has little to do with encoding or decoding such values according to the Basic, Canonical, Distinguished, Packed, Octet, XML, JSON, General String, or BACNet Encoding Rules. This library is purposely abstracted from any particular encoding so that ASN.1 values can be translated between different encodings. Other crates will use this library as a dependency to implement encoding and decoding for the types defined in this crate.

This crate is intended to be high-performance and opines toward more code in exchange for better performance, notably using a lot of SIMD and other optimizations. This is not a lightweight crate; it is intended to be a fast, feature-complete, meticulous, and well-tested ASN.1 crate.

§Feature Flags

atoi_simd - This will make integer parsing slightly faster, but only if you enable SIMD features at compile-time. See this crate’s documentation.
faster-hex - Faster hex compilation. Not tested to see if it’s really faster.
itoa - Faster integer printing, only in a few select cases like OIDs and DURATION values
likely_stable - Helps branch prediction, thereby making the code generally a little faster
smallvec - Use SmallVec<[u8; 16]> to store OBJECT IDENTIFIER, RELATIVE-OID and BIT STRING. Experimentation has shown this to be slower for some strange reason, so it should probably stay turned off.

§Capabilities

All universal types are supported, including the newer TIME subtypes: DATE, DATE-TIME, TIME-OF-DAY, and DURATION.

§`SEQUENCE` or `SET` parsing features

This is not a complete solution, but this library provides TagSelector for defining sequences of rules for matching components in a SEQUENCE or SET data types, and ComponentSpec for more data, such as the component’s name and whether it is OPTIONAL.

§Context-Switching Types

This library defines EXTERNAL, EMBEDDED_PDV, and CHARACTER_STRING. All of them can be printed.

§Display

All types defined in this crate implement Display, and when printed, they are printed according to their ASN.1 abstract syntax (which may differ from how they are encoded).

§Detailed Errors

ASN1Errors are very detailed, printable, and you should be able to figure out whatever your problem is based on the output:

pub struct ASN1Error {
    pub error_code: ASN1ErrorCode,
    pub component_name: Option<String>,
    pub tag: Option<Tag>,
    pub length: Option<usize>,
    pub constructed: Option<bool>,
    pub value_preview: Option<String>,
    pub bytes_read: Option<usize>, // The number of bytes into the IO read stream where this error appeared.
    pub values_read: Option<usize>, // The number of ASN.1 values into the IO read stream where this error appeared.
    pub err_source: Option<Box<dyn std::error::Error + 'static>>,
}

Of course, they implement std::error::Error.

There is a fluent API for elegantly creating errors, which is used like so:

let e = ASN1Error::new(super::ASN1ErrorCode::malformed_value)
    .with_tag(Tag::new(TagClass::UNIVERSAL, 10))
    .with_bytes_read(10)
    .with_values_read(5)
    .with_component_name("chunky")
    .with_construction(true)
    .with_preview("fogqwirg")
    .with_length(7)
    .with_source(src)
    ;

§ASN.1 Types and Values

ASN.1 abstract values can be represented via ASN1Value. This is a pretty large and complex enum. You probably should not use it unless you are parsing ASN.1 abstract values. When decoding presentation syntax (such as BER or DER), you probably should represent presentation values using the decoding libraries concept of a “node” or “value,” whatever that might be.

pub enum ASN1Value {
    BitStringValue(BIT_STRING),
    BooleanValue(BOOLEAN),
    ChoiceValue(Box<ASN1Value>),
    EmbeddedPDVValue(EMBEDDED_PDV),
    EnumeratedValue(ENUMERATED),
    ExternalValue(EXTERNAL),
    InstanceOfValue(INSTANCE_OF),
    IntegerValue(INTEGER),
    IRIValue(OID_IRI),
    NullValue,
    /// ...
}

§Embedded and `no-std` Use

This library is not ideal for embedded use cases. It is intended to be complete and compliant, not lightweight. Every valid ASN.1 requirement and capability is expected to be supported correctly, and if it is not, please report it as a bug.

This library is not no-std and probably never will be, because so many things in this library rely on std, and so few things outside of that are useful.

In embedded environments, it might be better for you to use encoding-specific, simpler libraries that do the bare minimum. This might be a suitable library for you in this case. Also consider that, since this library is licensed under an FLOSS license, you could just copy whatever code you need into your embedded project.

§`serde` Integration

I don’t think this crate will support integration with serde, unless this is requested. Its intended design is for dependent crates to implement most of the encoding-specific logic.

§Fuzz Testing

In the root of this monorepo, run:

cargo fuzz run bitstring
cargo fuzz run date -- -max_len=10
cargo fuzz run datetime -- -max_len=20
cargo fuzz run time_of_day -- -max_len=8
cargo fuzz run asn1utils -- -max_len=8
cargo fuzz run duration -- -max_len=32
cargo fuzz run gentime -- -max_len=35
cargo fuzz run utctime -- -max_len=20
cargo fuzz run oid -- -max_len=24

These will run forever, so you will want to kill them by pressing Ctrl+C.

Re-exports§

pub use bitstring::*;
pub use constants::*;
pub use construction::*;
pub use date::*;
pub use datetime::*;
pub use display::*;
pub use duration::*;
pub use error::*;
pub use external::*;
pub use gentime::*;
pub use oid::*;
pub use roid::*;
pub use strings::*;
pub use tag::*;
pub use time_of_day::*;
pub use utctime::*;
pub use utils::*;

Modules§

bitstring: The BIT STRING type
constants: Various ASN.1 constants
construction: Encoding, decoding, and validation of constructed types such as SET or SEQUENCE
date: The DATE type
datetime: The DATE-TIME type
display: Implementations of Display and functions for displaying / printing
duration: The DURATION type
error: The ASN1Error error type
external: Context-switching types: EXTERNAL, EMBEDDED PDV, and CharacterString
gentime: The GeneralizedTime type
oid: The OBJECT IDENTIFIER type
roid: The RELATIVE-OID type
strings: Functions for comparing, normalizing, and validating string types
tag: ASN.1 tags
time_of_day: The TIME-OF-DAY type
utctime: The UTCTime type
utils: Various utilities

Macros§

bits: Macro to define a bit string from raw bits.
octs: Create an OCTET STRING
oid: Convenience macro for creating object identifiers
roid: Convenience macro for creating relative object identifiers (ROIDs)

Structs§

BMPString: ASN.1 BMPString: Unicode code points encoded on two bytes each.
FractionalPart: Decimal digits fractional part
NamedType: A Named Type, such as would appear in the component type lists in a SET or SEQUENCE
TYPE_IDENTIFIER: ASN.1 TYPE-IDENTIFIER
UTCOffset: Coordinated Universal Time (UTC) Offset
UniversalString: ASN.1 UniversalString: Unicode code points encoded on four bytes each

Enums§

ASN1Value: ASN.1 value

Constants§

FALSE: Alias to make false look like ASN.1
TRUE: Alias to make true look like ASN.1
UNIV_TAG_BIT_STRING: The UNIVERSAL tag number for BIT STRING
UNIV_TAG_BMP_STRING: The UNIVERSAL tag number for BMPString
UNIV_TAG_BOOLEAN: The UNIVERSAL tag number for BOOLEAN
UNIV_TAG_CHARACTER_STRING: The UNIVERSAL tag number for CharacterString
UNIV_TAG_DATE: The UNIVERSAL tag number for DATE
UNIV_TAG_DATE_TIME: The UNIVERSAL tag number for DATE-TIME
UNIV_TAG_DURATION: The UNIVERSAL tag number for DURATION
UNIV_TAG_EMBEDDED_PDV: The UNIVERSAL tag number for EMBEDDED PDV
UNIV_TAG_END_OF_CONTENT: The UNIVERSAL tag number for END-OF-CONTENT
UNIV_TAG_ENUMERATED: The UNIVERSAL tag number for ENUMERATED
UNIV_TAG_EXTERNAL: The UNIVERSAL tag number for EXTERNAL
UNIV_TAG_GENERALIZED_TIME: The UNIVERSAL tag number for GeneralizedTime
UNIV_TAG_GENERAL_STRING: The UNIVERSAL tag number for GeneralString
UNIV_TAG_GRAPHIC_STRING: The UNIVERSAL tag number for GraphicString
UNIV_TAG_IA5_STRING: The UNIVERSAL tag number for IA5String
UNIV_TAG_INSTANCE_OF: The UNIVERSAL tag number for INSTANCE OF
UNIV_TAG_INTEGER: The UNIVERSAL tag number for INTEGER
UNIV_TAG_NULL: The UNIVERSAL tag number for NULL
UNIV_TAG_NUMERIC_STRING: The UNIVERSAL tag number for NumericString
UNIV_TAG_OBJECT_DESCRIPTOR: The UNIVERSAL tag number for ObjectDescriptor
UNIV_TAG_OBJECT_IDENTIFIER: The UNIVERSAL tag number for OBJECT IDENTIFIER
UNIV_TAG_OCTET_STRING: The UNIVERSAL tag number for OCTET STRING
UNIV_TAG_OID_IRI: The UNIVERSAL tag number for OID-IRI
UNIV_TAG_PRINTABLE_STRING: The UNIVERSAL tag number for PrintableString
UNIV_TAG_REAL: The UNIVERSAL tag number for REAL
UNIV_TAG_RELATIVE_OID: The UNIVERSAL tag number for RELATIVE-OID
UNIV_TAG_RELATIVE_OID_IRI: The UNIVERSAL tag number for RELATIVE-OID-IRI
UNIV_TAG_RESERVED_15: The reserved UNIVERSAL tag number 15
UNIV_TAG_SEQUENCE: The UNIVERSAL tag number for SEQUENCE
UNIV_TAG_SEQUENCE_OF: The UNIVERSAL tag number for SEQUENCE OF
UNIV_TAG_SET: The UNIVERSAL tag number for SET
UNIV_TAG_SET_OF: The UNIVERSAL tag number for SET OF
UNIV_TAG_T61_STRING: The UNIVERSAL tag number for T61String / TeletexString
UNIV_TAG_TIME: The UNIVERSAL tag number for TIME
UNIV_TAG_TIME_OF_DAY: The UNIVERSAL tag number for TIME-OF-DAY
UNIV_TAG_UNIVERSAL_STRING: The UNIVERSAL tag number for UniversalString
UNIV_TAG_UTC_TIME: The UNIVERSAL tag number for UTCTime
UNIV_TAG_UTF8_STRING: The UNIVERSAL tag number for UTF8String
UNIV_TAG_VIDEOTEX_STRING: The UNIVERSAL tag number for VideotexString
UNIV_TAG_VISIBLE_STRING: The UNIVERSAL tag number for VisibleString

Traits§

ASN1Codec: An ASN.1 Codec
ISO8601Timestampable: Something that can be converted into an ISO 8601 Timestamp
X690KnownSize: Anything that, when encoded as the content octets (“value”) of an X.690 Tag-Length-Value (TLV), will be encoded on a number of octets that can be trivially calculated, and does not vary with the choice of concrete syntax (BER, CER, or DER). This is so a codec can know in advance how many bytes a value will take up and pre-allocate them.
X690Validate: Trait for a type whose X.690 content octets can be validated in such a way that holds true for all X.690 codecs.

Type Aliases§

BIT_INDEX: Index into an ASN.1 BIT STRING
BOOLEAN: ASN.1 BOOLEAN
ByteSlice: How this library represents borrowed “bytes”
CHARACTER_STRING: ASN.1 CharacterString
DURATION: ASN.1 DURATION
EMBEDDED_PDV: ASN.1 EMBEDDED PDV
ENUMERATED: ASN.1 ENUMERATED
EXTERNAL: ASN.1 EXTERNAL
GeneralString: ASN.1 GeneralString
GraphicString: ASN.1 GraphicString
IA5String: ASN.1 IA5String
INSTANCE_OF: ASN.1 INSTANCE OF
INTEGER: ASN.1 INTEGER
NULL: An ASN.1 NULL value
NumericString: ASN.1 NumericString
OCTET_STRING: An ASN.1 OCTET STRING
OID_ARC: An arc within an ASN.1 OBJECT IDENTIFIER or RELATIVE-OID
OID_IRI: ASN.1 OBJECT IDENTIFIER Internationalized Resource Identifier (OID-IRI)
OPTIONAL: An alias to make Option<> look more like ASN.1.
ObjectDescriptor: ASN.1 ObjectDescriptor, which is defined as
PrintableString: ASN.1 PrintableString
REAL: ASN.1 REAL
RELATIVE_OID_IRI: ASN.1 RELATIVE-OID Internationalized Resource Identifier (Relative-OID-IRI)
SEQUENCE: ASN.1 SEQUENCE
SEQUENCE_OF: ASN.1 SEQUENCE OF
SET: ASN.1 SET
SET_OF: ASN.1 SET OF
T61String: ASN.1 T61String / TeletexString
TIME: ASN.1 TIME
TeletexString: ASN.1 T61String / TeletexString
UTF8String: ASN.1 UTF8String
VideotexString: ASN.1 VideotexString
VisibleString: ASN.1 VisibleString