pkce

Documentation

Overview

Package pkce implements PKCE (RFC 7636) code-verifier generation and code-challenge derivation/verification.

Generation is used by client when starting an authorization request; verification is used by server when redeeming an authorization code. Both sides share the same S256 transform so there is exactly one implementation of it to audit.

Index

• Variables
• func Challenge(verifier string, method Method) (string, error)
• func GenerateVerifier(random io.Reader) (string, error)
• func Verify(challenge string, method Method, verifier string) error
• type Method
  • func ParseMethod(s string) (Method, error)
  • func (m Method) String() string

Variables

var (
	// ErrPlainMethodNotPermitted indicates a code_challenge_method of
	// "plain" — a syntactically valid PKCE method this package refuses
	// to support, since it provides no protection against interception
	// of the authorization code.
	ErrPlainMethodNotPermitted = errors.New("pkce: plain code_challenge_method is not permitted")

	// ErrUnsupportedMethod indicates a code_challenge_method other than
	// "S256" or "plain" — something outside RFC 7636 entirely.
	ErrUnsupportedMethod = errors.New("pkce: unsupported code_challenge_method")

	// ErrInvalidVerifierSyntax indicates a code_verifier that does not
	// meet RFC 7636's length and character-set requirements.
	ErrInvalidVerifierSyntax = errors.New("pkce: invalid code_verifier syntax")

	// ErrChallengeMismatch indicates a code_verifier whose derived
	// challenge does not match the code_challenge on record.
	ErrChallengeMismatch = errors.New("pkce: code_verifier does not match code_challenge")
)

Functions

func Challenge

func Challenge(verifier string, method Method) (string, error)

Challenge derives the code_challenge for verifier under method.

func GenerateVerifier

func GenerateVerifier(random io.Reader) (string, error)

GenerateVerifier produces a new, random code_verifier. If random is nil, crypto/rand.Reader is used.

func Verify

func Verify(challenge string, method Method, verifier string) error

Verify checks that verifier, transformed under method, reproduces challenge — the code_challenge recorded when the authorization request was created. Callers must supply the method recorded alongside the challenge, not one read from the verifier's own request; Verify does not infer a method.

Types

type Method

type Method uint8

Method is a closed set of PKCE code_challenge_method values (RFC 7636 §4.2). It exists so a caller-supplied method string is never used as policy directly — S256 is the only method Verify or Challenge will act on.

const (

	// S256 derives code_challenge as
	// BASE64URL-ENCODE(SHA256(ASCII(code_verifier))).
	S256 Method
)

func ParseMethod

func ParseMethod(s string) (Method, error)

ParseMethod maps a code_challenge_method wire value to a Method. It distinguishes "plain" — syntactically valid per RFC 7636 but refused here — from every other unsupported value, and it does not default an empty string to "plain" the way RFC 7636 allows a bare authorization server to: an absent method must be treated as an error by the caller, never silently downgraded.

func (Method) String

func (m Method) String() string

String returns the wire value of m, or "" if m is not S256.