Struct bsn1::DerRef

source ·

pub struct DerRef { /* private fields */ }

Expand description

DerRef is a wrapper of [u8] and represents DER.

This struct is ‘Unsized’, and the user will usually use a reference.

Implementations§

source §

impl DerRef

source

pub const fn boolean(val: bool) -> &'static Self

Returns a reference to ‘boolean DER’ of val.

§Examples

use bsn1::{DerRef, IdRef};

let true_ = DerRef::boolean(true);
assert_eq!(true_.id(), IdRef::boolean());
assert_eq!(true_.contents().to_bool_der(), Ok(true));

let false_ = DerRef::boolean(false);
assert_eq!(false_.id(), IdRef::boolean());
assert_eq!(false_.contents().to_bool_der(), Ok(false));

source

pub fn parse<'a>(bytes: &mut &'a [u8]) -> Result<&'a Self, Error>

Parses bytes starting with octets of ‘ASN.1 DER’ and returns a reference to DerRef.

This function ignores extra octet(s) at the end of bytes if any.

On success, bytes is updated to point the next octet of DerRef; otherwise, bytes is not updated.

§Warnings

ASN.1 does not allow some universal identifiers for DER, however, this function accepts such an identifier. For example, ‘Octet String’ must be primitive in DER, but this function returns Ok for constructed Octet String DER.

§Examples

use bsn1::{Der, DerRef};

// Serializes '8' as Integer.
let der = Der::from(8_i32);
let mut serialized = Vec::from(der.as_ref() as &[u8]);

// Deserialize
{
    let mut serialized: &[u8] = &serialized[..];
    let deserialized = DerRef::parse(&mut serialized).unwrap();
    assert_eq!(der, deserialized);
    assert_eq!(serialized.len(), 0);
}

// The result is not changed even if extra octets are added to the end.
serialized.push(0xff);
serialized.push(0x00);

{
    let mut serialized: &[u8] = &serialized[..];
    let deserialized = DerRef::parse(&mut serialized).unwrap();
    assert_eq!(der, deserialized);
    assert_eq!(serialized, &[0xff, 0x00]);
}

source

pub fn parse_mut<'a>(bytes: &mut &'a mut [u8]) -> Result<&'a mut Self, Error>

Parses bytes starting with octets of ‘ASN.1 DER’ and returns a mutable reference to DerRef.

This function ignores extra octet(s) at the end of bytes if any.

On success, bytes is updated to point the next octet of DerRef; otherwise, bytes is not updated.

§Warnings

ASN.1 does not allow some universal identifiers for DER, however, this function accepts such an identifier. For example, ‘Octet String’ must be primitive in DER, but this function returns Ok for constructed Octet String DER.

§Examples

use bsn1::{Der, DerRef};

// Serialize "Foo" as utf8-string.
let der = Der::from("Foo");
let mut serialized = Vec::from(der.as_ref() as &[u8]);

// Deserialize.
{
    let mut serialized: &mut [u8] = serialized.as_mut();
    let deserialized = DerRef::parse_mut(&mut serialized).unwrap();
    assert_eq!(der, deserialized);
    assert_eq!(serialized.len(), 0);

    deserialized.mut_contents()[0] = 'B' as u8;
    assert_eq!(deserialized.contents().as_ref(), "Boo".as_bytes());
}

// Now `serialized` represents "Boo", not "Foo", because we changed via `deserialized`.

// Deserialize again.
{
    let mut serialized: &mut [u8] = serialized.as_mut();
    let deserialized = DerRef::parse_mut(&mut serialized).unwrap();

    assert_eq!(serialized.len(), 0);
    assert_ne!(der, deserialized);
    assert_eq!(deserialized.contents().as_ref(), "Boo".as_bytes());
}

source

pub const unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self

Provides a reference from bytes without any check.

bytes must not include any extra octet.

If it is not sure whether bytes is valid octets as a ‘DER’, use parse instead.

§Safety

The behaviour is undefined if bytes is not formatted as a DER.

§Examples

use bsn1::{Der, DerRef};

let der = Der::from(8_i32);
let serialized: Vec<u8> = Vec::from(der.as_ref() as &[u8]);
let deserialized = unsafe { DerRef::from_bytes_unchecked(&serialized[..]) };

assert_eq!(der, deserialized);

source

pub unsafe fn from_mut_bytes_unchecked(bytes: &mut [u8]) -> &mut Self

Provides a mutable reference from bytes without any check.

bytes must not include any extra octet.

If it is not sure whether bytes is valid octets as a ‘DER’, use parse_mut instead.

§Safety

The behaviour is undefined if bytes is not formatted as a DER.

§Examples

use bsn1::{Der, DerRef};

let der = Der::from(8_i32);
let mut serialized: Vec<u8> = Vec::from(der.as_ref() as &[u8]);
let deserialized = unsafe { DerRef::from_mut_bytes_unchecked(&mut serialized[..]) };

assert_eq!(der, deserialized);

deserialized.mut_contents()[0] += 1;

assert_ne!(der, deserialized);

source

pub fn id(&self) -> &IdRef

Returns a reference to the IdRef of self.

§Examples

use bsn1::{Der, DerRef, IdRef};

let der = Der::from(4_i32);
let der: &DerRef = der.as_ref();
assert_eq!(IdRef::integer(), der.id());

source

pub fn mut_id(&mut self) -> &mut IdRef

Returns a mutable reference to the IdRef of self.

§Examples

use bsn1::{ClassTag, Der, DerRef, PCTag};

let mut der = Der::from(4_i32);
let der: &mut DerRef = der.as_mut();

assert_eq!(der.id().class(), ClassTag::Universal);
der.mut_id().set_class(ClassTag::Private);
assert_eq!(der.id().class(), ClassTag::Private);

assert_eq!(der.id().pc(), PCTag::Primitive);
der.mut_id().set_pc(PCTag::Constructed);
assert_eq!(der.id().pc(), PCTag::Constructed);

source

pub fn length(&self) -> Length

Returns Length of self.

Note that DER does not allow indefinite Length. The return value is always Length::Definite.

§Warnings

Length stands for the length octets in DER: i.e. the length of the ‘contents octets’. The total byte count of the DER is greater than the value.

§Examples

use bsn1::{Der, DerRef, Length};

let der = Der::from("Foo");
let der: &DerRef = der.as_ref();

assert_eq!(Length::Definite("Foo".len()), der.length());

source

pub fn contents(&self) -> &ContentsRef

Returns a reference to the contents octets of self.

§Examples

use bsn1::{Der, DerRef};

let der = Der::from("Foo");
let der: &DerRef = der.as_ref();

assert_eq!(der.contents().as_ref(), "Foo".as_bytes());

source

pub fn mut_contents(&mut self) -> &mut ContentsRef

Returns a mutable reference to the ‘contents octets’ of self.

§Examples

use bsn1::{Der, DerRef};

let mut der = Der::from("Foo");
let der: &mut DerRef = der.as_mut();

assert_eq!(der.contents().as_ref(), "Foo".as_bytes());

der.mut_contents()[0] = 'B' as u8;
assert_eq!(der.contents().as_ref(), "Boo".as_bytes());

source

pub fn disassemble(&self) -> (&IdRef, Length, &ContentsRef)

Returns references to IdRef, Length, and ContentsRef of self.

§Examples

use bsn1::{Der, DerRef, IdRef};

let der = Der::from("Foo");
let der: &DerRef = der.as_ref();

let (id, length, contents) = der.disassemble();

assert_eq!(id, IdRef::utf8_string());
assert_eq!(length.definite().unwrap(), "Foo".len());
assert_eq!(contents.as_ref(), "Foo".as_bytes());

source

pub fn disassemble_mut(&mut self) -> (&mut IdRef, Length, &mut ContentsRef)

Returns mutable references to IdRef, Length, and ContentsRef of self.

§Examples

use bsn1::{Der, DerRef, IdRef};

let mut der = Der::from("Foo");
let der: &mut DerRef = der.as_mut();

let (id, length, contents) = der.disassemble_mut();

assert_eq!(id, IdRef::utf8_string());
assert_eq!(length.definite().unwrap(), "Foo".len());
assert_eq!(contents.as_ref(), "Foo".as_bytes());

contents[0] = 'B' as u8;
assert_eq!(der.contents().as_ref() as &[u8], "Boo".as_bytes());