diff --git a/src/private.rs b/src/private.rs index 80bb220..5b92f9a 100644 --- a/src/private.rs +++ b/src/private.rs @@ -1,15 +1,22 @@ use crate::Cookies; use cookie::{Cookie, Key}; -/// A child cookie jar that encrypts its cookies. +/// A cookie jar that provides authenticated encryption for its cookies. +/// +/// A _private_ child jar signs and encrypts all the cookies added to it and +/// verifies and decrypts cookies retrieved from it. Any cookies stored in +/// `PrivateCookies` are simultaneously assured confidentiality, integrity, and +/// authenticity. In other words, clients cannot discover nor tamper with the +/// contents of a cookie, nor can they fabricate cookie data. pub struct PrivateCookies<'a> { cookies: Cookies, key: &'a Key, } impl<'a> PrivateCookies<'a> { - /// Creates an instance of `PrivateCookies` with parent `cookies` and key `key`. This method is - /// typically called indirectly via the `private` method of [`Cookies`]. + /// Creates an instance of `PrivateCookies` with parent `cookies` and key `key`. + /// This method is typically called indirectly via the `private` + /// method of [`Cookies`]. pub(crate) fn new(cookies: &Cookies, key: &'a Key) -> Self { Self { cookies: cookies.clone(), @@ -17,14 +24,19 @@ impl<'a> PrivateCookies<'a> { } } - /// Adds cookie to the parent jar. The cookie’s value is encrypted. + /// Adds `cookie` to the parent jar. The cookie's value is encrypted with + /// authenticated encryption assuring confidentiality, integrity, and + /// authenticity. pub fn add(&self, cookie: Cookie<'static>) { let mut inner = self.cookies.inner.lock(); inner.changed = true; inner.jar().private_mut(self.key).add(cookie); } - /// Returns `Cookie` with the `name` and decrypted contents. + /// Returns a reference to the `Cookie` inside this jar with the name `name` + /// and authenticates and decrypts the cookie's value, returning a `Cookie` + /// with the decrypted value. If the cookie cannot be found, or the cookie + /// fails to authenticate or decrypt, `None` is returned. pub fn get(&self, name: &str) -> Option> { let mut inner = self.cookies.inner.lock(); inner.jar().private(self.key).get(name)