Crate ed25519_dalek::pkcs8::spki::der
pkcs8
only.Expand description
§RustCrypto: ASN.1 DER
Pure Rust embedded-friendly implementation of the Distinguished Encoding Rules (DER) for Abstract Syntax Notation One (ASN.1) as described in ITU X.690.
§About
This crate provides a no_std
-friendly implementation of a subset of ASN.1 DER
necessary for decoding/encoding the following cryptography-related formats
implemented as crates maintained by the RustCrypto project:
pkcs1
: RSA Cryptography Specificationspkcs5
: Password-Based Cryptography Specificationpkcs7
: Cryptographic Message Syntaxpkcs8
: Private-Key Information Syntax Specificationpkcs10
: Certification Request Syntax Specificationsec1
: Elliptic Curve Cryptographyspki
: X.509 Subject Public Key Infox501
: Directory Services Typesx509
: Public Key Infrastructure Certificate
The core implementation avoids any heap usage (with convenience methods
that allocate gated under the off-by-default alloc
feature).
The DER decoder in this crate performs checks to ensure that the input document is in canonical form, and will return errors if non-canonical productions are encountered. There is currently no way to disable these checks.
§Features
- Rich support for ASN.1 types used by PKCS/PKIX documents
- Performs DER canonicalization checks at decoding time
no_std
friendly: supports “heapless” usage- Optionally supports
alloc
andstd
if desired - No hard dependencies! Self-contained implementation with optional
integrations with the following crates, all of which are
no_std
friendly:const-oid
: const-friendly OID implementationpem-rfc7468
: PKCS/PKIX-flavored PEM library with constant-time decoder/encoderstime
crate: date/time library
§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.
§Usage
§Decode
and Encode
traits
The Decode
and Encode
traits provide the decoding/encoding API
respectively, and are designed to work in conjunction with concrete ASN.1
types, including all types which impl the Sequence
trait.
The traits are impl’d for the following Rust core types:
()
: ASN.1NULL
. See alsoNull
.bool
: ASN.1BOOLEAN
.i8
,i16
,i32
,i64
,i128
: ASN.1INTEGER
.u8
,u16
,u32
,u64
,u128
: ASN.1INTEGER
.f64
: ASN.1REAL
(gated onreal
crate feature)str
,String
: ASN.1UTF8String
.String
requiresalloc
feature. See alsoUtf8StringRef
.Option
: ASN.1OPTIONAL
.SystemTime
: ASN.1GeneralizedTime
. Requiresstd
feature.Vec
: ASN.1SEQUENCE OF
. Requiresalloc
feature.[T; N]
: ASN.1SEQUENCE OF
. See alsoSequenceOf
.
The following ASN.1 types provided by this crate also impl these traits:
Any
,AnyRef
: ASN.1ANY
.BitString
,BitStringRef
: ASN.1BIT STRING
GeneralizedTime
: ASN.1GeneralizedTime
.Ia5StringRef
: ASN.1IA5String
.Null
: ASN.1NULL
.ObjectIdentifier
: ASN.1OBJECT IDENTIFIER
.OctetString
,OctetStringRef
: ASN.1OCTET STRING
.PrintableStringRef
: ASN.1PrintableString
(ASCII subset).TeletexStringRef
: ASN.1TeletexString
.VideotexStringRef
: ASN.1VideotexString
.SequenceOf
: ASN.1SEQUENCE OF
.SetOf
,SetOfVec
: ASN.1SET OF
.UintRef
: ASN.1 unsignedINTEGER
with raw access to encoded bytes.UtcTime
: ASN.1UTCTime
.Utf8StringRef
: ASN.1UTF8String
.
Context specific fields can be modeled using these generic types:
ContextSpecific
: decoder/encoder for owned context-specific fieldsContextSpecificRef
: encode-only type for references to context-specific fields
§Example
The following example implements X.509’s AlgorithmIdentifier
message type
as defined in RFC 5280 Section 4.1.1.2.
The ASN.1 schema for this message type is as follows:
AlgorithmIdentifier ::= SEQUENCE {
algorithm OBJECT IDENTIFIER,
parameters ANY DEFINED BY algorithm OPTIONAL }
Structured ASN.1 messages are typically encoded as a SEQUENCE
, which
this crate maps to a Rust struct using the Sequence
trait. This
trait is bounded on the Decode
trait and provides a blanket impl
of the Encode
trait, so any type which impls Sequence
can be
used for both decoding and encoding.
The following code example shows how to define a struct which maps to the
above schema, as well as impl the Sequence
trait for that struct:
// Note: the following example does not require the `std` feature at all.
// It does leverage the `alloc` feature, but also provides instructions for
// "heapless" usage when the `alloc` feature is disabled.
use der::{
asn1::{AnyRef, ObjectIdentifier},
DecodeValue, Decode, SliceReader, Encode, Header, Reader, Sequence
};
/// X.509 `AlgorithmIdentifier`.
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub struct AlgorithmIdentifier<'a> {
/// This field contains an ASN.1 `OBJECT IDENTIFIER`, a.k.a. OID.
pub algorithm: ObjectIdentifier,
/// This field is `OPTIONAL` and contains the ASN.1 `ANY` type, which
/// in this example allows arbitrary algorithm-defined parameters.
pub parameters: Option<AnyRef<'a>>
}
impl<'a> DecodeValue<'a> for AlgorithmIdentifier<'a> {
fn decode_value<R: Reader<'a>>(reader: &mut R, _header: Header) -> der::Result<Self> {
// The `der::Decoder::Decode` method can be used to decode any
// type which impls the `Decode` trait, which is impl'd for
// all of the ASN.1 built-in types in the `der` crate.
//
// Note that if your struct's fields don't contain an ASN.1
// built-in type specifically, there are also helper methods
// for all of the built-in types supported by this library
// which can be used to select a specific type.
//
// For example, another way of decoding this particular field,
// which contains an ASN.1 `OBJECT IDENTIFIER`, is by calling
// `decoder.oid()`. Similar methods are defined for other
// ASN.1 built-in types.
let algorithm = reader.decode()?;
// This field contains an ASN.1 `OPTIONAL` type. The `der` crate
// maps this directly to Rust's `Option` type and provides
// impls of the `Decode` and `Encode` traits for `Option`.
// To explicitly request an `OPTIONAL` type be decoded, use the
// `decoder.optional()` method.
let parameters = reader.decode()?;
// The value returned from the provided `FnOnce` will be
// returned from the `any.sequence(...)` call above.
// Note that the entire sequence body *MUST* be consumed
// or an error will be returned.
Ok(Self { algorithm, parameters })
}
}
impl<'a> ::der::EncodeValue for AlgorithmIdentifier<'a> {
fn value_len(&self) -> ::der::Result<::der::Length> {
self.algorithm.encoded_len()? + self.parameters.encoded_len()?
}
fn encode_value(&self, writer: &mut impl ::der::Writer) -> ::der::Result<()> {
self.algorithm.encode(writer)?;
self.parameters.encode(writer)?;
Ok(())
}
}
impl<'a> Sequence<'a> for AlgorithmIdentifier<'a> {}
// Example parameters value: OID for the NIST P-256 elliptic curve.
let parameters = "1.2.840.10045.3.1.7".parse::<ObjectIdentifier>().unwrap();
// We need to convert `parameters` into an `Any<'a>` type, which wraps a
// `&'a [u8]` byte slice.
//
// To do that, we need owned DER-encoded data so that we can have
// `AnyRef` borrow a reference to it, so we have to serialize the OID.
//
// When the `alloc` feature of this crate is enabled, any type that impls
// the `Encode` trait including all ASN.1 built-in types and any type
// which impls `Sequence` can be serialized by calling `Encode::to_der()`.
//
// If you would prefer to avoid allocations, you can create a byte array
// as backing storage instead, pass that to `der::Encoder::new`, and then
// encode the `parameters` value using `encoder.encode(parameters)`.
let der_encoded_parameters = parameters.to_der().unwrap();
let algorithm_identifier = AlgorithmIdentifier {
// OID for `id-ecPublicKey`, if you're curious
algorithm: "1.2.840.10045.2.1".parse().unwrap(),
// `Any<'a>` impls `TryFrom<&'a [u8]>`, which parses the provided
// slice as an ASN.1 DER-encoded message.
parameters: Some(der_encoded_parameters.as_slice().try_into().unwrap())
};
// Serialize the `AlgorithmIdentifier` created above as ASN.1 DER,
// allocating a `Vec<u8>` for storage.
//
// As mentioned earlier, if you don't have the `alloc` feature enabled you
// can create a fix-sized array instead, then call `Encoder::new` with a
// reference to it, then encode the message using
// `encoder.encode(algorithm_identifier)`, then finally `encoder.finish()`
// to obtain a byte slice containing the encoded message.
let der_encoded_algorithm_identifier = algorithm_identifier.to_der().unwrap();
// Deserialize the `AlgorithmIdentifier` we just serialized from ASN.1 DER
// using `der::Decode::from_bytes`.
let decoded_algorithm_identifier = AlgorithmIdentifier::from_der(
&der_encoded_algorithm_identifier
).unwrap();
// Ensure the original `AlgorithmIdentifier` is the same as the one we just
// decoded from ASN.1 DER.
assert_eq!(algorithm_identifier, decoded_algorithm_identifier);
§Custom derive support
When the derive
feature of this crate is enabled, the following custom
derive macros are available:
Choice
: derive forCHOICE
enum (see [der_derive::Choice
])- [
Enumerated
]: derive forENUMERATED
enum (see [der_derive::Enumerated
]) Sequence
: derive forSEQUENCE
struct (see [der_derive::Sequence
])
§Derive Sequence
for struct
The following is a code example of how to use the Sequence
custom derive:
use der::{asn1::{AnyRef, ObjectIdentifier}, Encode, Decode, Sequence};
/// X.509 `AlgorithmIdentifier` (same as above)
#[derive(Copy, Clone, Debug, Eq, PartialEq, Sequence)] // NOTE: added `Sequence`
pub struct AlgorithmIdentifier<'a> {
/// This field contains an ASN.1 `OBJECT IDENTIFIER`, a.k.a. OID.
pub algorithm: ObjectIdentifier,
/// This field is `OPTIONAL` and contains the ASN.1 `ANY` type, which
/// in this example allows arbitrary algorithm-defined parameters.
pub parameters: Option<AnyRef<'a>>
}
// Example parameters value: OID for the NIST P-256 elliptic curve.
let parameters_oid = "1.2.840.10045.3.1.7".parse::<ObjectIdentifier>().unwrap();
let algorithm_identifier = AlgorithmIdentifier {
// OID for `id-ecPublicKey`, if you're curious
algorithm: "1.2.840.10045.2.1".parse().unwrap(),
// `Any<'a>` impls `From<&'a ObjectIdentifier>`, allowing OID constants to
// be directly converted to an `AnyRef` type for this use case.
parameters: Some(AnyRef::from(¶meters_oid))
};
// Encode
let der_encoded_algorithm_identifier = algorithm_identifier.to_der().unwrap();
// Decode
let decoded_algorithm_identifier = AlgorithmIdentifier::from_der(
&der_encoded_algorithm_identifier
).unwrap();
assert_eq!(algorithm_identifier, decoded_algorithm_identifier);
For fields which don’t directly impl Decode
and Encode
,
you can add annotations to convert to an intermediate ASN.1 type
first, so long as that type impls TryFrom
and Into
for the
ASN.1 type.
For example, structs containing &'a [u8]
fields may want them encoded
as either a BIT STRING
or OCTET STRING
. By using the
#[asn1(type = "BIT STRING")]
annotation it’s possible to select which
ASN.1 type should be used.
Building off the above example:
/// X.509 `SubjectPublicKeyInfo` (SPKI)
#[derive(Copy, Clone, Debug, Eq, PartialEq, Sequence)]
pub struct SubjectPublicKeyInfo<'a> {
/// X.509 `AlgorithmIdentifier`
pub algorithm: AlgorithmIdentifier<'a>,
/// Public key data
pub subject_public_key: BitStringRef<'a>,
}
§See also
For more information about ASN.1 DER we recommend the following guides:
- A Layman’s Guide to a Subset of ASN.1, BER, and DER (RSA Laboratories)
- A Warm Welcome to ASN.1 and DER (Let’s Encrypt)
Modules§
- Module containing all of the various ASN.1 built-in types supported by this library.
- RustCrypto: Object Identifiers (OIDs)
- RustCrypto: PEM Encoding (RFC 7468)
- A module for working with referenced data.
- Securely zero memory with a simple trait (
Zeroize
) built on stable Rust primitives which guarantee the operation will not be “optimized away”.
Structs§
- ASN.1
ANY
: represents any explicitly tagged ASN.1 value. - ASN.1
ANY
: represents any explicitly tagged ASN.1 value. - Date-and-time type shared by multiple ASN.1 types (e.g.
GeneralizedTime
,UTCTime
). - ASN.1 DER-encoded document.
- Reference encoder: wrapper type which impls
Encode
for any reference to a type which impls the same. - Reference value encoder: wrapper type which impls
EncodeValue
andTagged
for any reference type which impls the same. - Error type.
- ASN.1 DER headers: tag + length component of TLV-encoded values
- Length type with support for indefinite lengths as used by ASN.1 BER, as described in X.690 Section 8.1.3.6:
- ASN.1-encoded length.
- Reader type used by
Reader::read_nested
. - PemReader
pem
Reader
type which decodes PEM on-the-fly. Writer
type which outputs PEM-encoded data.- SecretDocument
zeroize
SecretDocument
type. Reader
which consumes an input byte slice.Writer
which encodes DER into a mutable output byte slice.- ASN.1 tag numbers (i.e. lower 5 bits of a
Tag
).
Enums§
- Class of an ASN.1 tag.
- Error type.
- ASN.1 tags.
- Tagging modes:
EXPLICIT
versusIMPLICIT
.
Traits§
- ASN.1
CHOICE
denotes a union of one or more possible alternatives. - Decoding trait.
- Marker trait for data structures that can be decoded from DER without borrowing any data from the decoder.
- DecodePem
pem
PEM decoding trait. - Decode the value part of a Tag-Length-Value encoded field, sans the [
Tag
] and [Length
]. - DER ordering trait.
- Encoding trait.
- EncodePem
pem
PEM encoding trait. - Encode the value part of a Tag-Length-Value encoded field, sans the [
Tag
] andLength
. - Types which have a constant ASN.1
Tag
. - Reader trait which reads DER-encoded input.
- Marker trait for ASN.1
SEQUENCE
s. - Types which have an ASN.1
Tag
. - DER value ordering trait.
- Writer trait which outputs encoded DER.
Type Aliases§
- Result type.