Skip to main content

Crate csexpr

Crate csexpr 

Source
Expand description

S-expressions, as specified by RFC 9804.

The name is short for canonical S-expression, which is what this format has long been called after the one representation of it that is unique, and by which it is known where it is used, as in SPKI and SDSI.

An S-expression is either an octet string or a list of simpler S-expressions (§2). Atom is the octet string, carrying the optional display hint of §4.6, and Sexp is the S-expression itself. Both are values, and neither holds any trace of how it was written, since §6 gives one S-expression three ways of being written and the choice among them belongs to whoever writes it.

encode writes an S-expression in the canonical representation of §6.2, which is the one to hash or sign, in the basic transport representation of §6.3, which survives a channel that would disturb raw octets, or in the advanced representation of §6.4, which is meant to be read by a person. decode reads all three, and narrows to whatever subset an application accepts through the restrictions §8 lists.

§Examples

use csexpr::{Atom, decode, encode::canonical, sexp};

let cert = sexp!["issuer", Atom::new("bob").with_hint("text/plain")];
let written = canonical::to_vec(&cert);

assert_eq!(written, b"(6:issuer[10:text/plain]3:bob)");
assert_eq!(decode::parse(&written).unwrap(), cert);

// The advanced representation of §6.4 carries the same value.
assert_eq!(cert.to_string(), "(issuer [text/plain]bob)");
assert_eq!(decode::parse(b"(issuer [text/plain]bob)").unwrap(), cert);

§Reading what cannot be trusted

Parsing takes no stack in proportion to how deeply the input nests, and no memory on the strength of a length the input states. What a parse builds is a tree, and dropping, cloning or comparing a tree does recurse, so a parser refuses input nested deeper than DEFAULT_MAX_DEPTH unless it is told otherwise. decode::Parser bounds the size of the input and of every octet string in it as well, and turns off whichever constructs an application has no use for.

This crate has no dependencies and contains no unsafe code.

Re-exports§

pub use crate::types::Atom;
pub use crate::types::Sexp;

Modules§

decode
Reading an S-expression from any representation of RFC 9804 §6.
encode
Writing an S-expression in the representations of RFC 9804 §6.
types
The values an S-expression is made of.

Macros§

sexp
Builds a list from values convertible into S-expressions.