Fill out rustdoc

This commit is contained in:
Thomas Gideon 2017-02-15 15:41:52 -05:00
parent acee9a8494
commit 6f7daf9a87
3 changed files with 22 additions and 2 deletions

View file

@ -5,12 +5,15 @@ use serde::{Deserialize, Serialize};
use serde_json;
use serde_json::value::{Value};
/// A default claim set, including the standard, or registered, claims and the ability to specify
/// your own as private claims.
#[derive(Debug, Default, PartialEq)]
pub struct Claims<T: Serialize + Deserialize> {
pub reg: Registered,
pub private: T
}
/// The registered claims from the spec.
#[derive(Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Registered {
pub iss: Option<String>,
@ -23,6 +26,7 @@ pub struct Registered {
}
impl<T: Serialize + Deserialize> Claims<T>{
/// Convenience factory method
pub fn new(reg: Registered, private: T) -> Claims<T> {
Claims {
reg: reg,
@ -32,6 +36,8 @@ impl<T: Serialize + Deserialize> Claims<T>{
}
impl<T: Serialize + Deserialize> Component for Claims<T> {
/// This implementation simply parses the base64 data twice, each time applying it to the
/// registered and private claims.
fn from_base64(raw: &str) -> Result<Claims<T>, Error> {
let data = try!(decode_config(raw, URL_SAFE));
let reg_claims: Registered = try!(serde_json::from_slice(&data));
@ -45,6 +51,8 @@ impl<T: Serialize + Deserialize> Component for Claims<T> {
})
}
/// Renders both the registered and private claims into a single consolidated JSON
/// representation before encoding.
fn to_base64(&self) -> Result<String, Error> {
if let Value::Object(mut reg_map) = serde_json::to_value(&self.reg)? {
if let Value::Object(pri_map) = serde_json::to_value(&self.private)? {

View file

@ -1,6 +1,7 @@
use std::default::Default;
use Header;
/// A default Header providing the type, key id and algorithm fields.
#[derive(Debug, PartialEq, Serialize, Deserialize)]
pub struct DefaultHeader {
pub typ: Option<HeaderType>,
@ -9,11 +10,13 @@ pub struct DefaultHeader {
}
/// Default value for the header type field.
#[derive(Debug, PartialEq, Serialize, Deserialize)]
pub enum HeaderType {
JWT,
}
/// Supported algorithms, each representing a valid signature and digest combination.
#[derive(Debug, PartialEq, Serialize, Deserialize)]
pub enum Algorithm {
HS256,
@ -34,6 +37,8 @@ impl Default for DefaultHeader {
}
}
/// Allow the rest of the library to access the configured algorithm without having to know the
/// specific type for the header.
impl Header for DefaultHeader {
fn alg(&self) -> &Algorithm {
&(self.alg)

View file

@ -18,6 +18,7 @@ pub mod header;
pub mod claims;
mod crypt;
/// Main struct representing a JSON Web Token, composed of a header and a set of claims.
#[derive(Debug, Default)]
pub struct Token<H, C>
where H: Component, C: Component {
@ -26,15 +27,19 @@ pub struct Token<H, C>
pub claims: C,
}
/// Any header type must implement this trait so that signing and verification work.
pub trait Header {
fn alg(&self) -> &header::Algorithm;
}
/// Any header or claims type must implement this trait in order to serialize and deserialize
/// correctly.
pub trait Component: Sized {
fn from_base64(raw: &str) -> Result<Self, Error>;
fn to_base64(&self) -> Result<String, Error>;
}
/// Provide a default implementation that should work in almost all cases.
impl<T> Component for T
where T: Serialize + Deserialize + Sized {
@ -53,6 +58,7 @@ impl<T> Component for T
}
}
/// Provide the ability to parse a token, verify it and sign/serialize it.
impl<H, C> Token<H, C>
where H: Component + Header, C: Component {
pub fn new(header: H, claims: C) -> Token<H, C> {
@ -74,7 +80,7 @@ impl<H, C> Token<H, C>
})
}
/// Verify a from_base64 token with a key and the token's specific algorithm
/// Verify a token with a key and the token's specific algorithm.
pub fn verify(&self, key: &[u8]) -> bool {
let raw = match self.raw {
Some(ref s) => s,
@ -88,7 +94,8 @@ impl<H, C> Token<H, C>
crypt::verify(sig, data, key, &self.header.alg())
}
/// Generate the signed token from a key and the specific algorithm
/// Generate the signed token from a key with the specific algorithm as a url-safe, base64
/// string.
pub fn signed(&self, key: &[u8]) -> Result<String, Error> {
let header = try!(Component::to_base64(&self.header));
let claims = try!(self.claims.to_base64());