Struct minerva_voucher::Voucher

source · [−]
pub struct Voucher { /* private fields */ }
Expand description

A structure implementing both “Voucher Request” and “Voucher” artifacts of Constrained BRSKI.

Implementations

Creates a new, empty “Voucher Request” instance.

Examples
use minerva_voucher::Voucher;

let mut vrq = Voucher::new_vrq();

Creates a new, empty “Voucher” instance.

Examples
use minerva_voucher::Voucher;

let mut vch = Voucher::new_vch();

Returns true if the voucher is a “Voucher Request” instance.

Examples
use minerva_voucher::Voucher;

let mut v = Voucher::new_vrq();
assert!(v.is_vrq());

Returns true if the voucher is a “Voucher” instance.

Examples
use minerva_voucher::Voucher;

let mut v = Voucher::new_vch();
assert!(v.is_vch());

Returns a reference to the attribute in the voucher, if any, that corresponds to the given attribute discriminant value.

Examples
use minerva_voucher::{Voucher, attr::*};

let mut vrq = Voucher::new_vrq();
vrq.set(Attr::CreatedOn(1475868702));

assert_eq!(vrq.get(ATTR_CREATED_ON), Some(&Attr::CreatedOn(1475868702)));
assert_eq!(vrq.get(ATTR_SERIAL_NUMBER), None);

Adds an attribute to the voucher, replacing the existing attribute, if any, that corresponds to the given one. Returns a mut reference to the voucher.

Panics

Panics if an invalid voucher attribute is being set.

Examples
use minerva_voucher::{Voucher, attr::*};

let mut vrq = Voucher::new_vrq();
assert_eq!(vrq.get(ATTR_CREATED_ON), None);

vrq.set(Attr::CreatedOn(1475868702));
assert_eq!(vrq.get(ATTR_CREATED_ON), Some(&Attr::CreatedOn(1475868702)));

vrq.set(Attr::CreatedOn(1599086034));
assert_eq!(vrq.get(ATTR_CREATED_ON), Some(&Attr::CreatedOn(1599086034)));

// Panics because `Attr::PinnedDomainPubk` is invalid for a "voucher request".
// vrq.set(Attr::PinnedDomainPubk(vec![]));

Removes an attribute from the voucher. Returns whether the attribute was present in the voucher.

Examples
use minerva_voucher::{Voucher, attr::*};

let mut vrq = Voucher::new_vrq();
vrq.set(Attr::CreatedOn(1475868702));

assert_eq!(vrq.remove(ATTR_CREATED_ON), true);
assert_eq!(vrq.remove(ATTR_CREATED_ON), false);

Removes and returns the attribute in the voucher, if any, that corresponds to the given attribute discriminant value.

Examples
use minerva_voucher::{Voucher, attr::*};

let mut vrq = Voucher::new_vrq();

vrq.set(Attr::CreatedOn(1475868702));
assert_eq!(vrq.take(ATTR_CREATED_ON), Some(Attr::CreatedOn(1475868702)));
assert_eq!(vrq.take(ATTR_CREATED_ON), None);

let sn = b"00-D0-E5-F2-00-02";
vrq.set(Attr::SerialNumber(sn.to_vec()));
assert_eq!(vrq.take(ATTR_SERIAL_NUMBER), Some(Attr::SerialNumber(sn.to_vec())));
assert_eq!(vrq.take(ATTR_SERIAL_NUMBER), None);

Returns the number of attributes in the voucher.

Examples
use minerva_voucher::{Voucher, attr::Attr};

let mut vrq = Voucher::new_vrq();
assert_eq!(vrq.len(), 0);
vrq.set(Attr::CreatedOn(1475868702));
assert_eq!(vrq.len(), 1);

Gets an iterator that visits the attributes in the voucher.

Examples
use minerva_voucher::{Voucher, attr::{Attr, Assertion}};

let mut vrq = Voucher::new_vrq();

vrq.set(Attr::Assertion(Assertion::Proximity))
    .set(Attr::CreatedOn(1599086034))
    .set(Attr::SerialNumber(b"00-D0-E5-F2-00-02".to_vec()));

let mut vrq_iter = vrq.iter();
assert!(vrq_iter.next().is_some());
assert!(vrq_iter.next().is_some());
assert!(vrq_iter.next().is_some());
assert!(vrq_iter.next().is_none());

Returns a tuple of references to the signature and its corresponding algorithm in the voucher, if any.

Examples
use minerva_voucher::{Voucher, SignatureAlgorithm};
use core::convert::TryFrom;

static VCH_F2_00_02: &[u8] = core::include_bytes!(
    concat!(env!("CARGO_MANIFEST_DIR"), "/data/00-D0-E5-F2-00-02/voucher_00-D0-E5-F2-00-02.vch"));

let vch = Voucher::new_vch();
assert_eq!(vch.get_signature(), None);

let vch = Voucher::try_from(VCH_F2_00_02).unwrap();
let (signature, alg) = vch.get_signature().unwrap();
assert_eq!(signature.len(), 64);
assert_eq!(*alg, SignatureAlgorithm::ES256);

Encodes the voucher into CBOR. Returns a CBOR byte string.

Errors

If the voucher is missing any mandatory attributes, then an error is returned.

Examples

See Encoding a Voucher into CBOR.

Returns a reference to the signer certificate in the voucher, if any.

Examples
use minerva_voucher::Voucher;

let mut vrq = Voucher::new_vrq();

assert_eq!(vrq.get_signer_cert(), None);
vrq.set_signer_cert(&[4, 186, 197, 177, 28, 173, 143, 153, 249, 199, 43, 5, 207, 75, 158, 38, 210, 68, 220, 24, 159, 116, 82, 40, 37, 90, 33, 154, 134, 214, 160, 158, 255, 32, 19, 139, 248, 45, 193, 182, 213, 98, 190, 15, 165, 74, 183, 128, 74, 58, 100, 182, 215, 44, 207, 237, 107, 111, 182, 237, 40, 187, 252, 17, 126]);
assert_eq!(vrq.get_signer_cert().unwrap().len(), 65);

Adds a singer certificate to the voucher. Returns a mut reference to the voucher.

Examples
use minerva_voucher::Voucher;

let mut vrq = Voucher::new_vrq();

assert_eq!(vrq.get_signer_cert(), None);
vrq.set_signer_cert(&[4, 186, 197, 177, 28, 173, 143, 153, 249, 199, 43, 5, 207, 75, 158, 38, 210, 68, 220, 24, 159, 116, 82, 40, 37, 90, 33, 154, 134, 214, 160, 158, 255, 32, 19, 139, 248, 45, 193, 182, 213, 98, 190, 15, 165, 74, 183, 128, 74, 58, 100, 182, 215, 44, 207, 237, 107, 111, 182, 237, 40, 187, 252, 17, 126]);
assert_eq!(vrq.get_signer_cert().unwrap().len(), 65);

Interfaces with meta data required for signing the voucher. This method needs to be used when implementing the Sign trait.

Returns a tuple of

Examples

See the default implementation of the Sign trait.

Interfaces with meta data required for validating the voucher. This method needs to be used when implementing the Validate trait.

Returns a tuple of

  • a reference to the signer certificate in the voucher, if any,
  • a tuple of references to the signature and its corresponding algorithm in the voucher, if any, and
  • a reference to the CBOR-encoded COSE_Sign1 structure for which validation is performed.
Examples

See the default implementation of the Validate trait.

Prints internal representation of the voucher for debugging purposes.

Examples
use minerva_voucher::Voucher;
use core::convert::TryFrom;

static VCH_JADA: &[u8] = core::include_bytes!(
    concat!(env!("CARGO_MANIFEST_DIR"), "/data/jada/voucher_jada123456789.vch"));

let vch = Voucher::try_from(VCH_JADA).unwrap();

vch.dump();
/* stdout:
======== Voucher::dump()
==== SidData::dump()
Voucher({VchTopLevel(VoucherVoucher), VchAssertion(Enumeration(Assertion(Proximity))), VchCreatedOn(DateAndTime(CreatedOn(1475868702))), VchExpiresOn(DateAndTime(ExpiresOn(1506816000))), VchNonce(Binary(Nonce([97, 98, 99, 100, 49, 50, 51, 52, 53]))), VchPinnedDomainPubk(Binary(PinnedDomainPubk([77, 70, 107, 119, 69, 119, 89, 72, 75, 111, 90, 73, 122, 106, 48, 67, 65, 81, 89, 73, 75, 111, 90, 73, 122, 106, 48, 68, 65, 81, 99, 68, 81, 103, 65, 69, 108, 109, 86, 81, 99, 106, 83, 54, 110, 43, 88, 100, 53, 108, 47, 50, 56, 73, 70, 118, 54, 85, 105, 101, 103, 81, 119, 83, 66, 122, 116, 71, 106, 53, 100, 107, 75, 50, 77, 65, 106, 81, 73, 80, 86, 56, 108, 56, 108, 72, 43, 69, 106, 76, 73, 79, 89, 100, 98, 74, 105, 73, 48, 86, 116, 69, 73, 102, 49, 47, 74, 113, 116, 43, 84, 79, 66, 102, 105, 110, 84, 78, 79, 76, 79, 103, 61, 61]))), VchSerialNumber(String(SerialNumber([74, 65, 68, 65, 49, 50, 51, 52, 53, 54, 55, 56, 57])))})
====
==== CoseSig::dump()
signature_type: ES256
signature: [len=64] [234, 232, 104, 236, 193, 118, 136, 55, 102, 197, 220, 91, 165, 184, 220, 162, 93, 171, 60, 46, 86, 165, 81, 206, 87, 5, 183, 147, 145, 67, 72, 225, 217, 85, 56, 95, 66, 111, 229, 137, 148, 12, 142, 214, 58, 86, 83, 68, 254, 186, 154, 162, 228, 175, 25, 168, 102, 60, 251, 36, 170, 105, 99, 194]
signer_cert: [len=65] [4, 186, 197, 177, 28, 173, 143, 153, 249, 199, 43, 5, 207, 75, 158, 38, 210, 68, 220, 24, 159, 116, 82, 40, 37, 90, 33, 154, 134, 214, 160, 158, 255, 32, 19, 139, 248, 45, 193, 182, 213, 98, 190, 15, 165, 74, 183, 128, 74, 58, 100, 182, 215, 44, 207, 237, 107, 111, 182, 237, 40, 187, 252, 17, 126]
to_verify: [len=202] [132, 106, 83, 105, 103, 110, 97, 116, 117, 114, 101, 49, 67, 161, 1, 38, 64, 88, 183, 161, 25, 9, 147, 166, 1, 105, 112, 114, 111, 120, 105, 109, 105, 116, 121, 2, 193, 26, 87, 247, 248, 30, 4, 193, 26, 89, 208, 48, 0, 11, 109, 74, 65, 68, 65, 49, 50, 51, 52, 53, 54, 55, 56, 57, 7, 105, 97, 98, 99, 100, 49, 50, 51, 52, 53, 9, 120, 124, 77, 70, 107, 119, 69, 119, 89, 72, 75, 111, 90, 73, 122, 106, 48, 67, 65, 81, 89, 73, 75, 111, 90, 73, 122, 106, 48, 68, 65, 81, 99, 68, 81, 103, 65, 69, 108, 109, 86, 81, 99, 106, 83, 54, 110, 43, 88, 100, 53, 108, 47, 50, 56, 73, 70, 118, 54, 85, 105, 101, 103, 81, 119, 83, 66, 122, 116, 71, 106, 53, 100, 107, 75, 50, 77, 65, 106, 81, 73, 80, 86, 56, 108, 56, 108, 72, 43, 69, 106, 76, 73, 79, 89, 100, 98, 74, 105, 73, 48, 86, 116, 69, 73, 102, 49, 47, 74, 113, 116, 43, 84, 79, 66, 102, 105, 110, 84, 78, 79, 76, 79, 103, 61, 61]
====
========
 */

Trait Implementations

Formats the value using the given formatter. Read more

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

This method tests for !=.

Signs the voucher using a PEM-encoded private key based on the signature algorithm alg.

Returns a &mut Self reference if the voucher is signed.

Errors

If the voucher is not signed, or the internal signing function fails, a VoucherError::SigningFailed is returned.

Examples
use minerva_voucher::{Voucher, attr::*, SignatureAlgorithm, Sign};

static KEY_PEM_F2_00_02: &[u8] = core::include_bytes!(
    concat!(env!("CARGO_MANIFEST_DIR"), "/data/00-D0-E5-F2-00-02/key.pem"));

// This is required when the `Sign` trait is backed by mbedtls.
minerva_voucher::init_psa_crypto();

let mut vrq = Voucher::new_vrq();

vrq.set(Attr::Assertion(Assertion::Proximity))
    .set(Attr::SerialNumber(b"00-D0-E5-F2-00-02".to_vec()));

assert!(vrq.get_signature().is_none());
vrq.sign(KEY_PEM_F2_00_02, SignatureAlgorithm::ES256).unwrap();
assert!(vrq.get_signature().is_some());

Decodes a CBOR-encoded voucher. Returns a Voucher.

Errors

If the voucher cannot be decoded, then an error is returned.

Examples

See Decoding a CBOR-encoded voucher into a Voucher.

The type returned in the event of a conversion error.

Validates the voucher using a PEM-encoded certificate. If the certificate pem is None, signer_cert attached to the voucher (see Voucher::set_signer_cert), if any, is used instead.

Returns a &Self reference if the voucher is validated.

Errors

If the voucher is not validated, or the internal validation function fails, a VoucherError::ValidationFailed is returned.

Examples
use minerva_voucher::{Voucher, Validate};
use core::convert::TryFrom;

static VCH_F2_00_02: &[u8] = core::include_bytes!(
    concat!(env!("CARGO_MANIFEST_DIR"), "/data/00-D0-E5-F2-00-02/voucher_00-D0-E5-F2-00-02.vch"));
static MASA_CRT_F2_00_02: &[u8] = core::include_bytes!(
    concat!(env!("CARGO_MANIFEST_DIR"), "/data/00-D0-E5-F2-00-02/masa.crt"));

// This is required when the `Validate` trait is backed by mbedtls.
minerva_voucher::init_psa_crypto();

let vch = Voucher::try_from(VCH_F2_00_02).unwrap();

assert!(vch.validate(Some(MASA_CRT_F2_00_02)).is_ok());

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.