Crate xmlsafe

An XML writer that protects you from XML injections through type safety.

• three marker traits mark the XML safety of Display implementations

• the streaming XmlWriter requires its arguments to implement these traits

• a tag! macro to structure your code (plays well with rustfmt)

If you forget to escape a string, your code just doesn’t compile. To prevent XML injections keep two things in mind:

1. Whenever you supply a string literal (&'static str), take care that it is syntactically valid for the respective context.

2. Whenever you implement one of the marker traits, take care that you fulfill its requirements.

Example

use std::fmt::Error;
use xmlsafe::{XmlWriter, format_text, escape_text, tag};

struct User {name: String, id: u8}

fn list_users(mut w: XmlWriter, users: Vec<User>) -> Result<(), Error> {
    tag!(w, "div", "class"="users", {
        w.write(format_text!("There are {} users:", users.len()))?;
        tag!(w, "ul", {
            for user in users {
                tag!(w, "li", "data-id"=user.id, {
                    w.write(escape_text(user.name))?;
                });
            }
        });
    });
    Ok(())
}

fn main() {
    let mut out = String::new();
    let users = vec![User{name: "Alice".into(), id: 3}, User{name: "Bob".into(), id: 5}];
    list_users(XmlWriter::new(&mut out), users).unwrap();
    assert_eq!(out, "<div class=\"users\">There are 2 users:\
        <ul><li data-id=\"3\">Alice</li><li data-id=\"5\">Bob</li></ul></div>");
}

Note how the XmlWriter acts as a protective layer between the actual write target (the String in our example) and the XML generation code. Also note that if we forgot the escape_text call, the example would not compile.

Safety

xmlsafe forbids unsafe code and does not panic.

Macros

format_att_value

Wraps format_args casting all arguments to AttValueSafe. The return value is wrapped to also implement AttValueSafe. Literal " and & characters in the format string must be escaped as " and &.

format_text

Wraps format_args casting all arguments to PcdataSafe. The return value is wrapped to also implement PcdataSafe. Literal < and & characters in the format string must be escaped as < and & respectively. Do NOT use this to build tags (instead use the secure methods from XmlWriter).

tag

Writes an XML tag to a given XmlWriter and takes care of closing the tag.

Structs

AttValueWriter

An XML attribute value writer returned by AttWriter::key.

AttWriter

An XML attribute writer returned by XmlWriter::open_start_tag.

XmlWriter

Encapsulates a std::fmt::Write target and prevents XML injections through marker traits and typestates.

Traits

AttValueSafe

Types whose Display implementation can be safely embedded in double-quoted XML attribute values. Literal " and & characters must be escaped as " and & respectively.

NameSafe

Types whose Display implementation can be safely used as an XML name.

PcdataSafe

Types whose Display implementation can be safely embedded between XML tags. Literal < and & characters must be escaped as < and & respectively.

TagConstructor

The tag! macro expects its first argument to implement this trait, see Tag constructors.

Functions

escape_att_value

XML escape an untrusted string to make it AttValueSafe.

escape_text

XML escape an untrusted string to make it PcdataSafe.