Struct bcder::string::OctetString

pub struct OctetString(/* private fields */);

An octet string value.

An octet string is a sequence of octets, i.e., a glorified [u8]. Basic Encoding Rules, however, allow this sequence to be broken up into chunks that are encoded separatedly to allow for very large octet strings and cases where one doesn’t yet know the length of the string.

In order to avoid unnecessary allocations, this type wraps the raw content octets of a BER encoded octet string. As a consequence, assembling the complete string may actually be costly and should only be done if really necessary. As an alternative, there is an iterator over the parts via the iter method or the IntoIterator trait as well as an iterator over the individual octets via the octets method.

Octet strings are sometimes used to store BER encoded data. The OctetStringSource type, accessible via the to_source method, provides an implementation of the Source trait to run a decoder on.

BER Encoding

Octet strings are either encoded as a primitive or a constructed value. In the primitive form, the content octets are the string’s octets. In a constructed form, the content is a sequence of encoded octets strings which in turn may be primitive or constructed. In this case, the string’s octets are the concatenation of all the content octets of the primitive forms in the order as encountered.

In CER, the string must use the primitive form if it is less than 1000 octets long and the constructed form otherwise. The constructed form must consists of a sequence of primitive values each exactly with a 1000 octets of content except for the last one.

In DER, only the primitive form is allowed.

Implementations

impl OctetString

Content Access

pub fn new(bytes: Bytes) -> Self

Creates an octet string from a Bytes value.

pub fn iter(&self) -> OctetStringIter<'_>

Returns an iterator over the parts of the octet string.

The iterator will produce &[u8] which, when appended produce the complete content of the octet string.

pub fn octets(&self) -> OctetStringOctets<'_>

Returns an iterator over the individual octets of the string.

pub fn as_slice(&self) -> Option<&[u8]>

Returns a reference to the complete content if possible.

The method will return a bytes slice of the content if the octet string was encoded as a single primitive value or None otherwise.

This is guaranteed to return some slice if the value was produced by decoding in DER mode.

pub fn to_bytes(&self) -> Bytes

Produces a bytes value with the string’s content.

If the octet string was encoded as a single primitive value, the method will simply clone the content. Otherwise it will produce an entirely new bytes value from the concatenated content of all the primitive values.

pub fn into_bytes(self) -> Bytes

Converts the octet string into bytes value.

If the octet string was encoded as a single primitive value, the method will simply return the content. Otherwise it will produce an entirely new bytes value from the concatenated content of all the primitive values.

pub fn len(&self) -> usize

Returns the length of the content.

This is not the length of the encoded value but of the actual octet string.

pub fn is_empty(&self) -> bool

Returns whether the content is empty.

impl OctetString

Parsing and Encoding of Octet Strings

pub fn take_from<S: Source>( cons: &mut Constructed<'_, S> ) -> Result<Self, DecodeError<S::Error>>

Takes a single octet string value from constructed value content.

If there is no next value, if the next value does not have the tag Tag::OCTET_STRING, or if it doesn’t contain a correctly encoded octet string, a malformed error is returned.

pub fn take_opt_from<S: Source>( cons: &mut Constructed<'_, S> ) -> Result<Option<Self>, DecodeError<S::Error>>

Takes an optional octet string value from constructed value content.

If there is no next value, or if the next value does not have the tag Tag::OCTET_STRING, then Ok(None) is returned.

If there is an octet string, but it is not correctly encoded, a malformed error is returned.

pub fn from_content<S: Source>( content: &mut Content<'_, S> ) -> Result<Self, DecodeError<S::Error>>

Takes an octet string value from content.

pub fn encode(self) -> impl Values

Returns a value encoder for the octet string using the natural tag.

pub fn encode_as(self, tag: Tag) -> impl Values

Returns a value encoder for the octet string using the given tag.

pub fn encode_ref(&self) -> impl Values + '_

Returns a value encoder for the octet string using the natural tag.

pub fn encode_ref_as(&self, tag: Tag) -> impl Values + '_

Returns a value encoder for the octet string using the given tag.

pub fn encode_wrapped<V: Values>(mode: Mode, values: V) -> impl Values

Returns a value encoder that wraps values into an octet string.

This function allows an octet string wrapping some values to be created without having to first create the octet string.

pub fn encode_slice<T>(value: T) -> OctetSliceEncoder<T>

Returns a value encoder that encodes a bytes slice as an octet string.

pub fn encode_slice_as<T>(value: T, tag: Tag) -> OctetSliceEncoder<T>

Returns a value encoder that encodes a bytes slice as an octet string.

Trait Implementations

impl AsRef<OctetString> for OctetString

fn as_ref(&self) -> &Self

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

impl<L: CharSet> AsRef<OctetString> for RestrictedString<L>

fn as_ref(&self) -> &OctetString

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

impl Clone for OctetString

fn clone(&self) -> OctetString

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OctetString

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

Formats the value using the given formatter.

impl Hash for OctetString

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

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> IntoIterator for &'a OctetString

type Item = &'a [u8]

The type of the elements being iterated over.

type IntoIter = OctetStringIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoSource for OctetString

type Source = OctetStringSource

fn into_source(self) -> Self::Source

impl Ord for OctetString

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<T: AsRef<[u8]>> PartialEq<T> for OctetString

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 OctetString

fn eq(&self, other: &OctetString) -> 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<T: AsRef<[u8]>> PartialOrd<T> for OctetString

fn partial_cmp(&self, other: &T) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd for OctetString

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for OctetString