Struct EmbeddedCert 

pub struct EmbeddedCert<VD, UR> {
    verified: Option<VD>,
    unverified: UR,
}

One certificate inside a netdoc, covering data other than the netdoc itself

Semantics and value

This type always embodies:

• The encoded form of a certificate or signature (its actual bytes, for encoding/decoding.

  This encoded unverified raw form is the type parameter UR. Often UR will be tor_cert::KeyUnknownCert.

Additionally, it can and usually does contain the “verified form”:

• Interpreted, parsed, data, of whatever was certified. For example, for a family certificate, the family IDs.

  It might or might not include something like a tor_cert::Ed25519Cert, depending whether downstreams need that information.

  This decoded verified data is the type parameter VD; EmbeddedCert contains Option<VD> (or equivalent).

(We call an EmbeddedCert without the verified form an “unverified EmbeddedCert”.)

Correctness/availability invariant

Whenever an EmbeddedCert appears in a parsed and verified network document body, the EmbeddedCert has been verified and the verified form is present.

During parsing of a network document, the document type’s verification function gets access to the unverified EmbeddedCert. It is the verify function which must verify and timecheck the certificate, and, if it is satisfied, call set_verified. Include fields of this type in documents deriving NetdocParseableUnverified, rather than plain NetdocParseable.

This invariant is somewhat fuzzy around the edges, and not 100% enforced by the compiler. If it is relied on inappropriately, or violated, Bug is thrown.

Security invariant

Presence of the verified form guarantees that, if the document came from outside, we have verified the signature, and checked that it is timely. So the interpreted form can safely be used.

This guarantee flows from the caller of set_verified, and may be relied on by users - eg, by callers of get.

Parsing and encoding

This type implements applicable parsing and encoding traits, if VD is EmbeddableCertObject<UR> and UR is Readable and Writable.

See EmbeddableCertObject for full details.

Example

See crates/tor-netdoc/src/types/embedded_cert/test.rs.

Fields

verified: Option<VD>

The verified form, if this EmbeddedCert is verified.

unverified: UR

The unverified form.

Implementations

impl<VD, UR> EmbeddedCert<VD, UR>

pub fn new(data: VD, raw: UR) -> Self

Make a new (verified) EmbeddedCert

Security

If this certificate originated elsewhere, it must have been verified and timechecked.

pub fn get(&self) -> Result<&VD, Bug>

Obtain the verified data

This function will always succeed on a cert found in a (verified) netdoc.

Error conditions

get will fail only if the correctness/availability invariant is violated or relied on inappropriately. See the type-level documentation.

It can fail inside a netdoc verification function, or after EmbeddedCert::new_unverified_hazardous. It could also fail if an EmbeddedCert is included in an unsigned netdoc (ie one to which derived plain NetdocParseable rather than NetdocParseableUnverified.

pub fn new_unverified_hazardous(unverified: UR) -> Self

Make a new unverified EmbeddedCert

Correctness

It is the caller’s responsibility to uphold the correctness/availability invariant. See the type-level documentation.

Carelessly creating a loose unverified EmbeddedCert could expose it to naive code, which expects get to succeed.

pub fn raw_unverified(&self) -> &UR

Obtain the raw data, for verification or encoding

pub fn set_verified(&mut self, verified: VD)

Set the verified data

Usually called from within a document-specific verify function.

Security

The signature must have been verified, and timeliness checked.

Trait Implementations

impl<VD: Clone, UR: Clone> Clone for EmbeddedCert<VD, UR>

fn clone(&self) -> EmbeddedCert<VD, UR>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<VD: Debug, UR: Debug> Debug for EmbeddedCert<VD, UR>

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

Formats the value using the given formatter.

impl<VD, UR> ItemObjectEncodable for EmbeddedCert<VD, UR>

where VD: EmbeddableCertObject<UR>, UR: Writeable,

fn label(&self) -> &str

The label (keyword(s) in BEGIN and END)

fn write_object_onto(&self, b: &mut Vec<u8>) -> Result<(), Bug>

Represent the actual value as bytes.

impl<VD, UR> ItemObjectParseable for EmbeddedCert<VD, UR>

where VD: EmbeddableCertObject<UR>, UR: Readable,

fn check_label(label: &str) -> Result<(), P2EP>

Check that the Label is right

fn from_bytes(input: &[u8]) -> Result<Self, P2EP>

Convert the bytes of the Object (which was present) into the actual value

impl<VD, UR> ItemValueEncodable for EmbeddedCert<VD, UR>

where Self: ItemObjectEncodable,

fn write_item_value_onto(&self, out: ItemEncoder<'_>) -> Result<(), Bug>

Write the item’s arguments, and any object, onto out

impl<VD, UR> ItemValueParseable for EmbeddedCert<VD, UR>

where VD: EmbeddableCertObject<UR>, UR: Readable,

fn from_unparsed(item: UnparsedItem<'_>) -> Result<Self, P2EP>

Parse the item’s value

impl<VD, UR> Writeable for EmbeddedCert<VD, UR>

where UR: Writeable,

fn write_onto<B: Writer + ?Sized>(&self, b: &mut B) -> Result<(), EncodeError>

Encode this object into the writer b.