pkce_std/lib.rs
1//! Handling Proof Key for Code Exchange.
2//!
3//! PKCE specification is defined in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636).
4//!
5//! # Abstract
6//!
7//! PKCE (pronounced "pixy") is a method to secure authorization codes in OAuth 2.0
8//! *authorization code* flow. It is designed to prevent interception attacks.
9//!
10//! # Abbreviations
11//!
12//! - `PKCE`: Proof Key for Code Exchange;
13//! - `Auth`: Authorization.
14//!
15//! # Protocol
16//!
17//! ```text
18//! +--------------+
19//! | Auth |
20//! +--------+ | +----------+ |
21//! | |--(1)- Auth Request + code_challenge ---->| | |
22//! | | + code_challenge_method | | Auth | |
23//! | | | | Endpoint | |
24//! | |<-(2)----------- Auth Code ---------------| | |
25//! | | | +----------+ |
26//! | Client | | |
27//! | | | +----------+ |
28//! | |--(3)- Token Request + code_verifier ---->| | |
29//! | | | | Tokens | |
30//! | | | | Endpoint | |
31//! | |<-(4)------------- Token -----------------| | |
32//! +--------+ | +----------+ |
33//! | Server |
34//! +--------------+
35//! ```
36//!
37//! ## 0. Code creation
38//!
39//! The *client* generates the `code_verifier` and derives the `code_challenge` from it
40//! using the `code_challenge_method`.
41//!
42//! ## 1. Auth Request
43//!
44//! The *client* sends the `code_challenge` and the `code_challenge_method` along with the
45//! regular `authorization_code` request to the *Auth Endpoint*.
46//!
47//! ## 2. Auth Code
48//!
49//! The *server* stores the `code_challenge` and the `code_challenge_method` for later use,
50//! responding with the usual authorization `code`.
51//!
52//! ## 3. Token Request
53//!
54//! The *client* sends the `code_verifier` along with the regular request to the *Tokens Endpoint*.
55//!
56//! ## 4. Token
57//!
58//! The *server* verifies the `code_verifier` against the stored `code_challenge` using the
59//! `code_challenge_method`, responding with the `token` if the verification is successful.
60//!
61//! # Examples
62//!
63//! Generating `code_verifier` and deriving `code_challenge` in one go:
64//!
65//! ```
66//! use pkce_std::Code;
67//!
68//! let code = Code::generate_default();
69//! ```
70//!
71//! Alternatively, generating from random bytes:
72//!
73//! ```
74//! use pkce_std::Code;
75//!
76//! let code = Code::generate_encode_default();
77//! ```
78//!
79//! Decoupling verifier and challenge:
80//!
81//! ```
82//! # use pkce_std::Code;
83//! #
84//! # let code = Code::generate_default();
85//! #
86//! let (verifier, challenge) = code.into_pair();
87//! ```
88//!
89//! Verifying `code_verifier` against `code_challenge`:
90//!
91//! ```
92//! # use pkce_std::Code;
93//! #
94//! # let (verifier, challenge) = Code::generate_default().into_pair();
95//! #
96//! let valid = verifier.verify(&challenge);
97//! ```
98
99#![deny(missing_docs)]
100#![cfg_attr(docsrs, feature(doc_auto_cfg))]
101
102pub mod challenge;
103pub mod check;
104pub mod code;
105pub mod count;
106pub mod encoding;
107pub mod generate;
108pub mod hash;
109pub mod length;
110pub mod method;
111
112#[macro_use]
113pub mod verifier;
114
115pub use challenge::Challenge;
116pub use code::{Code, Pair};
117pub use count::Count;
118pub use length::Length;
119pub use method::Method;
120pub use verifier::Verifier;