1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
use std::borrow::Cow;

use crate::primitives::grant::{GrantExtension, Value};

use base64;
use sha2::{Digest, Sha256};
use subtle::ConstantTimeEq;

/// Proof Key for Code Exchange by OAuth Public Clients
///
/// > Auth 2.0 public clients utilizing the Authorization Code Grant are
/// susceptible to the authorization code interception attack.  This
/// specification describes the attack as well as a technique to mitigate
/// against the threat through the use of Proof Key for Code Exchange
/// (PKCE, pronounced "pixy").
///
/// (from the respective [RFC 7636])
///
/// In short, public clients share a verifier for a secret token when requesting their initial
/// authorization code. When they then make a second request to the autorization server, trading
/// this code for an access token, they can credible assure the server of their identity by
/// presenting the secret token.
///
/// The simple `plain` method only prevents attackers unable to snoop on the connection from
/// impersonating the client, while the `S256` method, which uses one-way hash functions, makes
/// any attack short of reading the victim client's memory infeasible.
///
/// Support for the `plain` method is OPTIONAL and must be turned on explicitely.
///
/// [RFC 7636]: https://tools.ietf.org/html/rfc7636
pub struct Pkce {
    required: bool,
    allow_plain: bool,
}

enum Method {
    Plain(String),
    Sha256(String),
}

impl Pkce {
    /// A pkce extensions which requires clients to use it.
    pub fn required() -> Pkce {
        Pkce {
            required: true,
            allow_plain: false,
        }
    }

    /// Pkce extension which will check verifiers if present but not require them.
    pub fn optional() -> Pkce {
        Pkce {
            required: false,
            allow_plain: false,
        }
    }

    /// Allow usage of the less secure `plain` verification method. This method is NOT secure
    /// an eavesdropping attacker such as rogue processes capturing a devices requests.
    pub fn allow_plain(&mut self) {
        self.allow_plain = true;
    }

    /// Create the encoded method for proposed method and challenge.
    ///
    /// The method defaults to `plain` when none is given, effectively offering increased
    /// compatibility but less security. Support for `plain` is optional and needs to be enabled
    /// explicitely through `Pkce::allow_plain`. This extension may also require clients to use it,
    /// in which case giving no challenge also leads to an error.
    ///
    /// The resulting string MUST NOT be publicly available to the client. Otherwise, it would be
    /// trivial for a third party to impersonate the client in the access token request phase. For
    /// a SHA256 methods the results would not be quite as severe but still bad practice.
    pub fn challenge(
        &self, method: Option<Cow<str>>, challenge: Option<Cow<str>>,
    ) -> Result<Option<Value>, ()> {
        let method = method.unwrap_or(Cow::Borrowed("plain"));

        let challenge = match challenge {
            None if self.required => return Err(()),
            None => return Ok(None),
            Some(challenge) => challenge,
        };

        let method = Method::from_parameter(method, challenge)?;
        let method = method.assert_supported_method(self.allow_plain)?;

        Ok(Some(Value::private(Some(method.encode()))))
    }

    /// Verify against the encoded challenge.
    ///
    /// When the challenge is required, ensure again that a challenge was made and a corresponding
    /// method data is present as an extension. This is not strictly necessary since clients should
    /// not be able to delete private extension data but this check does not cost a lot.
    ///
    /// When a challenge was agreed upon but no verifier is present, this method will return an
    /// error.
    pub fn verify(&self, method: Option<Value>, verifier: Option<Cow<str>>) -> Result<(), ()> {
        let (method, verifier) = match (method, verifier) {
            (None, _) if self.required => return Err(()),
            (None, _) => return Ok(()),
            // An internal saved method but no verifier
            (Some(_), None) => return Err(()),
            (Some(method), Some(verifier)) => (method, verifier),
        };

        let method = match method.into_private_value() {
            Ok(Some(method)) => method,
            _ => return Err(()),
        };

        let method = Method::from_encoded(Cow::Owned(method))?;

        method.verify(&verifier)
    }
}

impl GrantExtension for Pkce {
    fn identifier(&self) -> &'static str {
        "pkce"
    }
}

/// Base 64 encoding without padding
fn b64encode(data: &[u8]) -> String {
    base64::encode_config(data, base64::URL_SAFE_NO_PAD)
}

impl Method {
    fn from_parameter(method: Cow<str>, challenge: Cow<str>) -> Result<Self, ()> {
        match method.as_ref() {
            "plain" => Ok(Method::Plain(challenge.into_owned())),
            "S256" => Ok(Method::Sha256(challenge.into_owned())),
            _ => Err(()),
        }
    }

    fn assert_supported_method(self, allow_plain: bool) -> Result<Self, ()> {
        match (self, allow_plain) {
            (this, true) => Ok(this),
            (Method::Sha256(content), false) => Ok(Method::Sha256(content)),
            (Method::Plain(_), false) => Err(()),
        }
    }

    fn encode(self) -> String {
        match self {
            Method::Plain(challenge) => challenge + "p",
            Method::Sha256(challenge) => challenge + "S",
        }
    }

    fn from_encoded(encoded: Cow<str>) -> Result<Method, ()> {
        // TODO: avoid allocation in case of borrow and invalid.
        let mut encoded = encoded.into_owned();
        match encoded.pop() {
            None => Err(()),
            Some('p') => Ok(Method::Plain(encoded)),
            Some('S') => Ok(Method::Sha256(encoded)),
            _ => Err(()),
        }
    }

    fn verify(&self, verifier: &str) -> Result<(), ()> {
        match self {
            Method::Plain(encoded) => {
                if encoded.as_bytes().ct_eq(verifier.as_bytes()).into() {
                    Ok(())
                } else {
                    Err(())
                }
            }
            Method::Sha256(encoded) => {
                let mut hasher = Sha256::new();
                hasher.update(verifier.as_bytes());
                let b64digest = b64encode(&hasher.finalize());
                if encoded.as_bytes().ct_eq(b64digest.as_bytes()).into() {
                    Ok(())
                } else {
                    Err(())
                }
            }
        }
    }
}