Struct bsn1::BerRef

pub struct BerRef { /* private fields */ }

BerRef is a wrapper of [u8] and represents a BER.

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

Warnings

ASN.1 allows BER both ‘definite’ and ‘indefinite’ length octets. In case of ‘indefinite’, the contents must be a sequence of BERs, and must be terminated by ‘EOC BER’. (Single ‘EOC BER’ is allowed.)

A reference to BerRef works fine even if the user violates the rule, however, the inner slice will be invalid as a BER then. Such a slice can not be parsed as a BER again.

Implementations

impl BerRef

pub const fn eoc() -> &'static Self

Returns a reference to ‘End-of-Contents’.

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

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

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

On success, bytes will be updated to point the next octet of BerRef; otehrwise, bytes will not be updated.

Warnings

ASN.1 reserves some universal identifier numbers and they should not be used, however, this function ignores the rule. For example, number 15 (0x0f) is reserved for now, but this functions returns Ok.

Examples

use bsn1::{Ber, BerRef};

// Serializes '8' as an Integer.
let ber = Ber::from(8_u8);
let mut serialized = Vec::from(ber.as_ref() as &[u8]);

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

// Extra octets at the end does not affect the result.
serialized.push(0x00);
serialized.push(0xff);
{
    let mut serialized: &[u8] = &serialized[..];
    let deserialized = BerRef::parse(&mut serialized).unwrap();
    assert_eq!(ber, deserialized);
    assert_eq!(serialized, &[0x00, 0xff]);
}

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

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

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

On success, bytes will be updated to point the next octet of BerRef; otehrwise, bytes will not be updated.

Warnings

ASN.1 reserves some universal identifier numbers and they should not be used, however, this function ignores the rule. For example, number 15 (0x0f) is reserved for now, but this functions returns Ok.

Examples

use bsn1::{Ber, BerRef};

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

// Deserialize.
let deserialized = BerRef::parse_mut(&mut &mut serialized[..]).unwrap();
assert_eq!(ber, deserialized);

// You can update it because 'deserialized' is a mutable reference.
deserialized.mut_contents()[0] = 'B' as u8;
assert_eq!(Ber::from("Boo").as_ref() as &BerRef, deserialized);

// Now deserialize represents "Boo", not "Foo".

// Deserialize again.
let deserialized = BerRef::parse_mut(&mut &mut serialized[..]).unwrap();
assert_eq!(Ber::from("Boo").as_ref() as &BerRef, deserialized);

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

Provides a reference from bytes without any check.

bytes must be BER octets and must not include any extra octet.

If it is not sure whether bytes are valid octets as an ‘BER’, use parse instead.

Safety

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

Examples

use bsn1::{Ber, BerRef};

let ber = Ber::from(0x34_u8);
let serialized: &[u8] = ber.as_ref();
let deserialized = unsafe { BerRef::from_bytes_unchecked(serialized) };

assert_eq!(ber, deserialized);

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

Provides a reference from bytes without any check.

bytes must be BER octets and must not include any extra octet.

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

Safety

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

Examples

use bsn1::{Ber, BerRef};

let ber = Ber::from(0x34_u8);
let mut serialized: Vec<u8> = Vec::from(ber.as_ref() as &[u8]);
let deserialized = unsafe { BerRef::from_mut_bytes_unchecked(&mut serialized[..]) };

assert_eq!(ber, deserialized);

deserialized.mut_contents()[0] += 1;
assert_ne!(ber, deserialized);

pub fn id(&self) -> &IdRef

Provides a reference to the IdRef of self.

Examples

use bsn1::{Ber, BerRef, IdRef};

let ber = Ber::from(0x05_u8);
let ber: &BerRef = &ber;

assert_eq!(ber.id(), IdRef::integer());

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

Provides a mutable reference to the IdRef of self.

Examples

use bsn1::{Ber, BerRef, ClassTag, IdRef, PCTag};

let mut ber = Ber::from(0x05_u8);
let ber: &mut BerRef = &mut ber;

assert_eq!(ber.id(), IdRef::integer());

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

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

pub fn length(&self) -> Length

Returns the Length of self.

Warnings

Length stands for ‘the length octets’ in BER. It implies the byte count of contents or indefinite. The total byte count is greater than the value even if it is definite.

Examples

use bsn1::{Ber, BerRef, Length};

let ber = Ber::from(false);
let ber: &BerRef = &ber;

assert_eq!(ber.length(), Length::Definite(ber.contents().len()));

pub fn contents(&self) -> &ContentsRef

Provides a reference to the ContentsRef of self.

Examples

use bsn1::{Ber, BerRef};

let ber = Ber::from(false);
let ber: &BerRef = &ber;

assert_eq!(ber.contents().to_bool_ber(), Ok(false));

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

Provides a mutable reference to the ContentsRef of self.

Examples

use bsn1::{Ber, BerRef, ContentsRef};

let mut ber = Ber::from(false);
let ber: &mut BerRef = &mut ber;

assert_eq!(ber.contents().to_bool_ber(), Ok(false));

let true_contents: &ContentsRef = true.into();
ber.mut_contents().as_mut().copy_from_slice(true_contents.as_ref());
assert_eq!(ber.contents().to_bool_ber(), Ok(true));

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

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

Examples

use bsn1::{Ber, BerRef, IdRef};

let ber = Ber::from("Foo");
let ber: &BerRef = ber.as_ref();

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

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

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

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

Examples

use bsn1::{Ber, BerRef, IdRef};

let mut ber = Ber::from("Foo");
let ber: &mut BerRef = ber.as_mut();

let (id, length, contents) = ber.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!(ber.contents().as_ref() as &[u8], "Boo".as_bytes());

Trait Implementations

impl AsMut<BerRef> for Ber

fn as_mut(&mut self) -> &mut BerRef

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<[u8]> for BerRef

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<BerRef> for Ber

fn as_ref(&self) -> &BerRef

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<BerRef> for Ber

fn borrow(&self) -> &BerRef

Immutably borrows from an owned value.

impl Debug for BerRef

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&BerRef> for Ber

fn from(ber_ref: &BerRef) -> Self

Converts to this type from the input type.

impl<'a> From<&'a DerRef> for &'a BerRef

fn from(der: &'a DerRef) -> Self

Converts to this type from the input type.

impl Hash for BerRef

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

impl<T> PartialEq<T> for BerRef

where T: Borrow<BerRef>,

fn eq(&self, other: &T) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for BerRef

fn eq(&self, other: &BerRef) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl ToOwned for BerRef

type Owned = Ber

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl Eq for BerRef

impl StructuralPartialEq for BerRef