kizzycode / asn1_der-rust

This library provides a simple ASN.1-DER en-/decoder

asn1_der

Welcome to asn1_der 🎉

This crate provides a basic no_std-compatible, no-panic and zero-copy DER implementation. It is designed to be reliable and reasonable fast without getting too large or sacrificing too much comfort. To achieve this, asn1_der makes extensive use of the no-panic crate and offers slice-based object views to avoid allocations and unnecessary copies.

Example

use asn1_der::{
    DerObject,
    typed::{ DerEncodable, DerDecodable }
};

fn main() {
    /// An ASN.1-DER encoded integer `7`
    const INT7: &'static[u8] = b"\x02\x01\x07";

    // Decode an arbitrary DER object
    let object = DerObject::decode(INT7).expect("Failed to decode object");

    // Encode an arbitrary DER object
    let mut encoded_object = Vec::new();
    object.encode(&mut encoded_object).expect("Failed to encode object");

    // Decode a `u8`
    let number = u8::decode(INT7).expect("Failed to decode number");
    assert_eq!(number, 7);

    // Encode a new `u8`
    let mut encoded_number = Vec::new();
    7u8.encode(&mut encoded_number).expect("Failed to encode number");
}

For the (de-)serialization of structs and similar via derive, see serde_asn1_der.

Typed Implementations

There are also some direct DerDecodable/DerDecodable implementations for native Rust type equivalents:

• The ASN.1-BOOLEAN type as Rust-bool
• The ASN.1-INTEGER type as Rust-[u8, u16, u32, u64, u128, usize]
• The ASN.1-NULL type as either () or Option::None (which allows the encoding of optionals)
• The ASN.1-OctetString type as Vec<u8>
• The ASN.1-SEQUENCE type as SequenceVec(Vec<T>)
• The ASN.1-UTF8String type as String

No-Panic

asn1_der is designed to be as panic-free as possible. To ensure that, nearly every function is attributed with #[no_panic], which forces the compiler to prove that a function cannot panic in the given circumstances. However since no_panic can cause a lot of false-positives, it is currently only used by the CI-tests and disabled by default in normal builds. If you want to use this crate with no_panic enabled, you can do so by specifying the no_panic feature.

What No-Panic Does Not Cover

It is important to know that no_panic is no silver bullet and does not help against certain kinds of errors that can also happen in this crate. This especially includes:

• Dynamic memory allocation errors: Since it is not possible to predict memory allocation errors, everything that requires dynamic memory allocation is mutually exclusive to no_panic and will be omitted if no_panic is enabled.

  This crate might allocate memory in the following circumstances:

  • When writing to a dynamically allocating sink (e.g. Vec<u8>, VecBacking(Vec<u8>))
  • When decoding a native owned type such as Vec<u8>, SequenceVec(Vec<T>) or String
  • During error propagation

  If the crate is compiled without std enabled, it does performy any dynamic memory allocation directly by itself – however for foreign implementations passed to this crate may still allocate memory and fail (e.g. a custom Sink implementation).

• Stack overflows: Since the stack size is not necessarily known during compile time, it is not possible to predict stack overflow errors e.g. caused by recursion.

• Calls to abort or similar: Since calls to abort or similar do not trigger stack unwinding, they can also no be detected by no_panic. This also means that no_panic does not work for builds that use panic = "abort" in their config.

  This crate by itself does never call abort directly.

Due to the limitations described above, the following functions are mutually exclusive to no_panic and disabled if no_panic is set:

• Error stacking/propagation (propagate is a no-op if compiled with no_panic)
• The sink implementation for a byte vector (impl Sink for Vec<u8>)
• The VecBacking(Vec<u8>) type
• The native OctetString type which uses Vec<u8> (impl<'a> DerDecodable<'a> for Vec<u8> and impl DerEncodable for Vec<u8>)
• The native Sequence type wrapper SequenceVec since it is based upon Vec
• The native Utf8String type based upon String (impl<'a> DerDecodable<'a> for String and impl DerEncodable for String)

Zero-Copy

The crate is designed to be as much zero-copy as possible. In fact this means that the DerObject type and all typed views are zero-copy views over the underlying slice. Of course, zero-copy is not always reasonable: The new-constructors are not zero-copy because they construct a new object into a sink and the native type implementations are not zero-copy because they are either Copy-types (e.g. u128) or owned (e.g. String).

What happened to asn1_der_derive?

Since version 0.7.0, the asn1_der_derive-crates has been deprecated in favor of serde_asn1_der. If you have a specific use-case why you cannot use serde, let me know; it's probably not that hard to revive asn1_der_derive 😊

asn1_der-rust's Issues

Unchecked length can cause memory allocation error.

When de-serializing bytes, an arbitrary length of the value can be specified. When building data_buf here:
https://github.com/KizzyCode/asn1_der/blob/master/src/der/value.rs#L17
This can lead to memory crashes for arbitrary large length values. Perhaps an upper bound is required to prevent crashing applications when de serializing arbitrary byte arrays.

This can be reproduced in the following example:

use asn1_der::{Asn1Der, FromDerObject};

#[derive(Asn1Der)]
struct Test {
    inner: String,
}

fn main() {
    let bytes = [
        157, 247, 157, 157, 157, 157, 157, 157, 157, 157, 157, 157, 157, 157, 157, 67, 157, 1, 0,
        0, 0, 157, 157, 157, 157, 157, 157, 157, 157,
    ];
    let _ = Test::deserialize(bytes.iter());
}

Installation and usage?

• As a novice both in ASN.1 encoding and Rust, I'd appreciate a dedicated section for installation/usage guide.

• I found this project through github search. The README only makes sense if read from crates.io, where the github repo is linked at the top. Maybe put this link at the README forefront or the repo About? https://crates.io/crates/asn1_der

LICENSE BSD 2-CLAUSE contained in this repository is divergent

The current version on master (https://github.com/KizzyCode/asn1_der-rust/blob/60743ebaebdb621c47ad254b0e5987a9ba8cafde/LICENSE%20BSD%202-CLAUSE.md) appears to diverge in the wording from the online texts I have found of that license.

https://opensource.org/licenses/BSD-2-Clause

https://spdx.org/licenses/BSD-2-Clause.html

In both of the above online sources, in the part where it says:

THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT

The version in this repository says COPYRIGHT OWNER instead of COPYRIGHT HOLDER.

---

I only caught this divergence through a tool I am developing for the legal team at my company. Please bear in mind that I don't have licensing knowledge nor can say if the texts are equivalent, however I do think the license should not be branded as "BSD-2-Clause" if the text is anyhow different from the official one.

Parsing OBJECT IDENTIFIER (OID)

Is it possible to parse OIDs using that library?

Why are older crates.io versions being yanked?

I noticed that all versions older than 0.6.2 have been yanked from crates.io. Is there a particular reason for this? Yanking is meant only to remove packages that have specific breaking issues: https://doc.rust-lang.org/cargo/reference/publishing.html#managing-a-cratesio-based-crate.