jwt

func Base64Decode ¶

func Base64Decode(src []byte) ([]byte, error)

Base64Decode decodes JWT-specific base64url format bytes to raw data.

JWT tokens use base64url encoding (RFC 4648 Section 5) without trailing padding characters. This function handles the JWT-specific decoding by automatically adding required padding before standard base64 decoding.

The decoding process:

• Calculates missing padding length based on input length
• Adds appropriate number of '=' padding characters
• Performs standard base64.URLEncoding decode operation
• Returns the raw decoded bytes

This function is used internally for decoding JWT headers, payloads, and signatures. It correctly handles the padding-free format used in JWT tokens.

Parameters:

• src: Base64url-encoded bytes (without padding)

Returns:

• []byte: Decoded raw bytes
• error: Decoding error if the input is invalid base64url

The function automatically handles inputs with or without padding, making it compatible with both JWT format and standard base64url.

Example:

encoded := []byte("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9")
decoded, err := jwt.Base64Decode(encoded)
if err != nil {
    log.Fatal(err)
}
// Result: []byte(`{"alg":"HS256","typ":"JWT"}`)

func Base64Encode ¶

func Base64Encode(src []byte) []byte

Base64Encode encodes bytes to JWT-specific base64url format without padding.

JWT tokens use base64url encoding (RFC 4648 Section 5) without trailing padding characters ('='). This function provides optimized encoding that follows JWT specifications exactly.

The encoding process:

• Uses standard base64.URLEncoding for initial encoding
• Removes trailing '=' padding characters as required by JWT spec
• Returns URL-safe base64 encoded bytes

This function is used internally for encoding JWT headers, payloads, and signatures. While optimized for internal use, it can be used externally for compatible base64url encoding needs.

Parameters:

• src: Raw bytes to encode

Returns:

• []byte: Base64url-encoded bytes without padding

Example:

data := []byte(`{"alg":"HS256","typ":"JWT"}`)
encoded := jwt.Base64Encode(data)
// Result: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
// Note: No trailing '=' characters

func BytesQuote ¶ added in v0.0.4

func BytesQuote(b []byte) []byte

BytesQuote wraps a byte slice in double quotes to create a JSON string value.

This function creates a new byte slice with the input data surrounded by double quotes, making it suitable for use as a JSON string value.

The function allocates a new slice that is exactly len(b)+2 bytes long and copies the input data between the quotes.

Example:

token := []byte("eyJhbGciOiJIUzI1NiJ9...")
quoted := jwt.BytesQuote(token)
// quoted = []byte("\"eyJhbGciOiJIUzI1NiJ9...\"")

This is primarily used internally by NewTokenPair but can be useful for other JSON formatting scenarios.

func BytesToString ¶

func BytesToString(b []byte) string

BytesToString converts a byte slice to a string without memory allocation.

This function uses unsafe operations to avoid copying the underlying byte data, providing better performance for frequent conversions. The resulting string shares the same underlying memory as the input byte slice.

WARNING: This is unsafe because:

• If the byte slice is modified after conversion, the string changes too
• The string will be invalid if the byte slice is garbage collected
• Only use when you control the lifecycle of both the bytes and string

This implementation requires Go 1.20+ for unsafe.String and unsafe.SliceData. For safer builds, use the "safe" build tag which provides a standard conversion.

Example:

data := []byte("hello")
str := jwt.BytesToString(data) // No allocation
// Do NOT modify data after this point

func EncodePrivateKeyToPEM ¶ added in v0.1.15

func EncodePrivateKeyToPEM(key PrivateKey) (string, error)

EncodePrivateKeyToPEM converts a private key to PEM-encoded string format.

This function supports encoding of private keys for the following algorithms:

• RSA: Encodes as PKCS#1 format ("RSA PRIVATE KEY")
• ECDSA: Encodes as SEC1 format ("EC PRIVATE KEY")
• Ed25519: Encodes as PKCS#8 format ("PRIVATE KEY")

The resulting PEM string can be saved to files, stored in configuration, or transmitted securely. It's the inverse operation of the Parse* functions.

Returns an error if the key type is not supported for PEM encoding.

Example:

privateKey, _ := rsa.GenerateKey(rand.Reader, 2048)
pemString, err := jwt.EncodePrivateKeyToPEM(privateKey)
if err != nil {
    log.Fatal(err)
}

// Save to file
err = os.WriteFile("private.pem", []byte(pemString), 0600)

func EncodePublicKeyToPEM ¶ added in v0.1.15

func EncodePublicKeyToPEM(key PublicKey) (string, error)

EncodePublicKeyToPEM converts a public key to PEM-encoded string format.

This function supports encoding of public keys for the following algorithms:

• RSA: Encodes in PKIX format ("PUBLIC KEY")
• ECDSA: Encodes in PKIX format ("PUBLIC KEY")
• Ed25519: Encodes in PKIX format ("PUBLIC KEY")

The resulting PEM string is safe to share publicly and can be distributed for token verification. It's commonly used for JWKS generation and configuration file storage.

Returns an error if the key type is not supported for PEM encoding.

Example:

publicKey := &privateKey.PublicKey // From RSA private key
pemString, err := jwt.EncodePublicKeyToPEM(publicKey)
if err != nil {
    log.Fatal(err)
}

// Include in JWKS or configuration
config := KeyConfiguration{
    Public: pemString,
    // ... other fields
}

func Enrich ¶ added in v0.1.16

func Enrich(key PrivateKey, accessToken []byte, extraClaims any) ([]byte, error)

Enrich creates a new JWT token by merging claims from an existing token with additional claims.

This function takes an existing JWT token, extracts its claims, merges them with the provided extra claims, and creates a new properly signed token using the same algorithm as the original token. This is useful for scenarios where external systems need to add role-based fields or other metadata to existing tokens while preserving the original claims.

Important: It's not possible to modify just the payload of a JWT without changing the signature, since the signature is calculated over the entire header.payload content. This function creates a completely new token with a new signature.

Parameters:

• key: Key for both verifying the original token and signing the new token
• accessToken: Existing JWT token to extract claims from
• extraClaims: Additional claims to merge with existing claims

Algorithm Detection: The algorithm is automatically extracted from the original token's header, ensuring the enriched token uses the same algorithm as the original.

Claim Merging Behavior:

• Original token claims are preserved
• Extra claims are merged without extra validation
• Uses the same merging logic as the Sign function

Security Considerations:

• The original token should be verified by the caller before claim extraction
• The new token is properly signed with the same algorithm and provided key
• Consider the security implications of merging untrusted extra claims
• Validate extra claims before passing them to this function
• Encrypted tokens are not supported

Use Cases:

• Adding role-based permissions to existing user tokens
• Enriching tokens with organization-specific data
• Token transformation in microservice architectures
• Adding audit trails or metadata to existing tokens

Example usage:

// Basic enrichment with role information
extraClaims := map[string]any{
    "role":        "admin",
    "permissions": []string{"read", "write", "delete"},
    "department":  "engineering",
}

enrichedToken, err := jwt.Enrich(signingKey, existingToken, extraClaims)
if err != nil {
    log.Printf("Token enrichment failed: %v", err)
    return
}

// Enrichment with additional standard claims
organizationInfo := jwt.Map{
    "org_id":   "org123",
    "org_name": "MyCompany",
    "tenant":   "tenant456",
}

enrichedToken, err := jwt.Enrich(signingKey, userToken,
    organizationInfo,
    jwt.MaxAge(2 * time.Hour),        // Extend expiration
    jwt.Audience{"enriched-api"})     // Add new audience

// Role-based enrichment
roleData := struct {
    Role        string   `json:"role"`
    Permissions []string `json:"permissions"`
    Level       int      `json:"access_level"`
}{
    Role:        "manager",
    Permissions: []string{"user_management", "reporting"},
    Level:       5,
}

enrichedToken, err := jwt.Enrich(signingKey, originalToken, roleData)

Error Conditions:

• Unsupported or invalid algorithm in original token
• Claim extraction or merging failures
• New token signing failures
• Invalid extra claims (non-JSON serializable)

Performance Notes:

• It does not verify the original token
• Performs JSON marshaling and unmarshaling operations
• Creates a completely new token with new signature
• Consider caching enriched tokens if appropriate for your use case

func GenerateBase64EdDSA ¶ added in v0.0.14

func GenerateBase64EdDSA() (string, string, error)

GenerateBase64EdDSA generates a random Ed25519 key pair as base64-encoded strings.

This function generates a new Ed25519 key pair and returns the keys as base64-encoded strings using raw standard encoding (no padding). This format is convenient for configuration files or environment variables.

Returns the public key string, private key string, and any error that occurred.

Example:

publicKey, privateKey, err := jwt.GenerateBase64EdDSA()
if err != nil {
    log.Fatal(err)
}
// Use keys directly or store in config
fmt.Printf("Public Key: %s\n", publicKey)
fmt.Printf("Private Key: %s\n", privateKey)

func GenerateEdDSA ¶ added in v0.0.14

func GenerateEdDSA() (ed25519.PublicKey, ed25519.PrivateKey, error)

GenerateEdDSA generates a random Ed25519 key pair and returns them as PEM-encoded data.

This function generates a new Ed25519 key pair and encodes both keys in PEM format (PKCS#8 for private key, PKIX for public key).

Returns the public key PEM, private key PEM, and any error that occurred. Note: The returned order is (publicPEM, privatePEM), which differs from the conventional (private, public) order.

Example:

publicPEM, privatePEM, err := jwt.GenerateEdDSA()
if err != nil {
    log.Fatal(err)
}
// Save to files or use directly

func HasRequiredJSONTag ¶ added in v0.0.4

func HasRequiredJSONTag(field reflect.StructField) bool

HasRequiredJSONTag reports whether a struct field has the "required" JSON tag.

This function checks if a struct field is marked as required using the `json:"fieldname,required"` tag syntax. It only considers exported fields (fields with uppercase first letter).

This function is useful for:

• Pre-validation of struct definitions
• Building custom unmarshaling logic
• Debugging required field configurations

Example:

type Claims struct {
    Username string `json:"username,required"`
    Email    string `json:"email"`
}

field, _ := reflect.TypeOf(Claims{}).FieldByName("Username")
isRequired := jwt.HasRequiredJSONTag(field) // returns true

func LoadHMAC ¶

func LoadHMAC(filenameOrRaw string) ([]byte, error)

LoadHMAC loads an HMAC key from a file or treats the input as raw key data.

If the input is a valid file path, it reads the file contents as the key. Otherwise, it treats the input string as raw key data and converts it to []byte. This provides flexibility for both file-based and inline key configuration.

Pass the returned value to both Sign and Verify functions.

Returns an error if the file exists but cannot be read.

Example:

// Load from file
key, err := jwt.LoadHMAC("secret.key")
if err != nil {
    log.Fatal(err)
}

// Use raw string (never fails)
key, _ := jwt.LoadHMAC("my-secret-key-here")

token, err := jwt.Sign(jwt.HS256, key, claims)

func LoadPrivateKeyECDSA ¶

func LoadPrivateKeyECDSA(filename string) (*ecdsa.PrivateKey, error)

LoadPrivateKeyECDSA loads and parses a PEM-encoded ECDSA private key from a file.

The file should contain a PEM-encoded ECDSA private key in PKCS#1 or PKCS#8 format. Pass the returned value to Sign functions for token creation.

Returns an error if the file cannot be read or the key cannot be parsed.

Example:

privateKey, err := jwt.LoadPrivateKeyECDSA("ecdsa_private_key.pem")
if err != nil {
    log.Fatal(err)
}
token, err := jwt.Sign(jwt.ES256, privateKey, claims)

func LoadPrivateKeyEdDSA ¶

func LoadPrivateKeyEdDSA(filename string) (ed25519.PrivateKey, error)

LoadPrivateKeyEdDSA loads and parses a PEM-encoded Ed25519 private key from a file.

The file should contain a PEM-encoded Ed25519 private key in PKCS#8 format. Pass the returned value to Sign functions for token creation.

Returns an error if the file cannot be read or the key cannot be parsed.

Example:

privateKey, err := jwt.LoadPrivateKeyEdDSA("ed25519_private_key.pem")
if err != nil {
    log.Fatal(err)
}
token, err := jwt.Sign(jwt.EdDSA, privateKey, claims)

func LoadPrivateKeyRSA ¶

func LoadPrivateKeyRSA(filename string) (*rsa.PrivateKey, error)

LoadPrivateKeyRSA loads and parses a PEM-encoded RSA private key from a file.

The file should contain a PEM-encoded RSA private key in PKCS#1 or PKCS#8 format. Pass the returned value to Sign functions for token creation.

Returns an error if the file cannot be read or the key cannot be parsed.

Example:

privateKey, err := jwt.LoadPrivateKeyRSA("rsa_private_key.pem")
if err != nil {
    log.Fatal(err)
}
token, err := jwt.Sign(jwt.RS256, privateKey, claims)

func LoadPublicKeyECDSA ¶

func LoadPublicKeyECDSA(filename string) (*ecdsa.PublicKey, error)

LoadPublicKeyECDSA loads and parses a PEM-encoded ECDSA public key from a file.

The file should contain a PEM-encoded ECDSA public key in PKIX format, or a certificate containing an ECDSA public key. Pass the returned value to Verify functions for token validation.

Returns an error if the file cannot be read or the key cannot be parsed.

Example:

publicKey, err := jwt.LoadPublicKeyECDSA("ecdsa_public_key.pem")
if err != nil {
    log.Fatal(err)
}
verifiedToken, err := jwt.Verify(jwt.ES256, publicKey, token)

func LoadPublicKeyEdDSA ¶

func LoadPublicKeyEdDSA(filename string) (ed25519.PublicKey, error)

LoadPublicKeyEdDSA loads and parses a PEM-encoded Ed25519 public key from a file.

The file should contain a PEM-encoded Ed25519 public key in PKIX format. Pass the returned value to Verify functions for token validation.

Returns an error if the file cannot be read or the key cannot be parsed.

Example:

publicKey, err := jwt.LoadPublicKeyEdDSA("ed25519_public_key.pem")
if err != nil {
    log.Fatal(err)
}
verifiedToken, err := jwt.Verify(jwt.EdDSA, publicKey, token)

func LoadPublicKeyRSA ¶

func LoadPublicKeyRSA(filename string) (*rsa.PublicKey, error)

LoadPublicKeyRSA loads and parses a PEM-encoded RSA public key from a file.

The file should contain a PEM-encoded RSA public key in PKIX format, or a certificate containing an RSA public key. Pass the returned value to Verify functions for token validation.

Returns an error if the file cannot be read or the key cannot be parsed.

Example:

publicKey, err := jwt.LoadPublicKeyRSA("rsa_public_key.pem")
if err != nil {
    log.Fatal(err)
}
verifiedToken, err := jwt.Verify(jwt.RS256, publicKey, token)

func MaxAgeMap ¶

func MaxAgeMap(maxAge time.Duration, claims Map)

MaxAgeMap sets expiration and issued-at claims directly in a map-based claims structure.

This helper function provides expiration functionality for map-based claims (Map type) by directly setting the "exp" and "iat" fields. It's designed for use with custom claim structures that don't embed the standard Claims struct.

**Parameters**:

• maxAge: Duration the token should remain valid from current time
• claims: Map containing JWT claims (modified in-place)

**Behavior**:

• If claims is nil: Function returns immediately (no-op)
• If maxAge <= 1 second: Function returns immediately (no expiration set)
• If "exp" already exists: Preserves existing expiration (no overwrite)
• Otherwise: Sets both "exp" and "iat" to calculated values

**Claims Set**:

• "exp": Current time + maxAge duration (Unix timestamp)
• "iat": Current time (Unix timestamp)

**Time Source**: Uses the configurable Clock() function for current time, ensuring consistency with other JWT timing operations.

**Use Cases**:

• Custom claim structures using map[string]any
• Dynamic claim building without predefined structs
• Legacy codebases using map-based claims
• Flexible claim composition patterns

**Preservation Logic**: The function checks if "exp" is already set to avoid overwriting existing expiration times, allowing for selective application.

Example usage:

// Create custom claims with expiration
claims := jwt.Map{
    "user_id": "12345",
    "role":    "admin",
    "scope":   []string{"read", "write"},
}

// Add 15-minute expiration
jwt.MaxAgeMap(15 * time.Minute, claims)
token, err := jwt.Sign(jwt.HS256, secretKey, claims)

// Respects existing expiration
claimsWithExpiry := jwt.Map{
    "user_id": "12345",
    "exp":     time.Now().Add(time.Hour).Unix(), // Preserved
}
jwt.MaxAgeMap(15 * time.Minute, claimsWithExpiry) // No change to exp

// Use before signing
claims := jwt.Map{"foo": "bar"}
jwt.MaxAgeMap(15 * time.Minute, claims)
jwt.Sign(alg, key, claims)

func Merge ¶

func Merge(values ...any) ([]byte, error)

Merge combines multiple values into a single JSON object for JWT claims.

This utility function merges a variadic number of values into a unified JSON object, enabling flexible composition of JWT claims from multiple sources. It's used internally by the Sign function and can be used directly for custom claim composition scenarios.

**Input Requirements**:

• Each non-nil value must marshal to a valid JSON object
• Objects must start with '{' and end with '}'
• Nil values are safely ignored
• Empty objects ("{}") are skipped during merging

**Supported Input Types**:

• Structs with JSON tags (Claims, custom claim structs)
• map[string]any and similar map types
• []byte containing valid JSON object
• string containing valid JSON object
• Any type implementing json.Marshaler for objects

**Merging Logic**:

• Values are processed in order (left to right)
• Later values can override earlier values for same keys
• Object contents are merged at the top level
• Returns combined JSON as []byte

**Error Conditions**:

• Returns error if any value fails to marshal
• Returns error if marshaled result is not a JSON object
• Includes position information in error messages

**Automatic Usage**: This function is automatically called by Sign when multiple SignOption values are provided, enabling seamless claim composition.

Example usage:

// Merge standard and custom claims
standardClaims := jwt.Claims{
    Issuer:  "myapp.com",
    Subject: "user123",
    Expiry:  time.Now().Add(time.Hour).Unix(),
}

customClaims := map[string]any{
    "role":        "admin",
    "permissions": []string{"read", "write", "delete"},
    "department":  "engineering",
}

// Direct merge usage
combined, err := jwt.Merge(standardClaims, customClaims)
if err != nil {
    log.Fatal(err)
}
token, err := jwt.Sign(jwt.HS256, secretKey, combined)

// Automatic merge in Sign function
token, err := jwt.Sign(jwt.HS256, secretKey, customClaims,
    jwt.MaxAge(15 * time.Minute),  // Adds exp, iat
    jwt.Claims{Issuer: "myapp.com"}) // Adds iss

// Multiple map merging
userInfo := map[string]any{"user_id": "123", "email": "user@example.com"}
permissions := map[string]any{"role": "user", "scope": "read"}
metadata := map[string]any{"version": "1.0", "client": "mobile"}

allClaims, err := jwt.Merge(userInfo, permissions, metadata)

**Note**: When the same key exists in multiple objects, the last occurrence takes precedence, allowing for override patterns in claim composition.

func MustGenerateRandom ¶

func MustGenerateRandom(n int) []byte

MustGenerateRandom generates a cryptographically secure random byte slice of length n. This is suitable for creating HMAC keys.

For HMAC algorithms, recommended key sizes are: - HS256: 32 bytes - HS384: 48 bytes - HS512: 64 bytes

This function panics if random generation fails. Use crypto/rand.Read directly for error handling.

Example:

key := jwt.MustGenerateRandom(32) // For HS256
token, err := jwt.Sign(jwt.HS256, key, claims)

func MustGenerateRandomBase64 ¶ added in v0.0.14

func MustGenerateRandomBase64(length int, padding rune) string

MustGenerateRandomBase64 generates a cryptographically secure random base64-encoded string.

The length parameter specifies the number of random bytes to generate before encoding. The padding parameter controls base64 padding ('=' characters). Use jwt.NoPadding or base64.NoPadding to disable padding.

This function panics if random generation fails.

Example:

// Generate 32 random bytes, base64-encoded without padding
randomB64 := jwt.MustGenerateRandomBase64(32, jwt.NoPadding)

// Generate 24 random bytes, base64-encoded with standard padding
randomB64 := jwt.MustGenerateRandomBase64(24, base64.StdPadding)

func MustGenerateRandomString ¶ added in v0.0.14

func MustGenerateRandomString(length int) string

MustGenerateRandomString generates a cryptographically secure random string of the specified length. The string contains only letters (a-z, A-Z).

This function uses a secure random number generator and efficient bit manipulation to generate random strings suitable for keys, tokens, or identifiers.

This function panics if random generation fails.

Example:

randomStr := jwt.MustGenerateRandomString(32)
fmt.Println(randomStr) // Output: "aBcDeFgHiJkLmNoPqRsTuVwXyZ..."

func MustLoadECDSA ¶

func MustLoadECDSA(privateKeyFilename, publicKeyFilename string) (*ecdsa.PrivateKey, *ecdsa.PublicKey)

MustLoadECDSA accepts private and public PEM filenames and returns a pair of private and public ECDSA keys.

Pass the returned private key to the Sign functions and the public key to the Verify functions.

This function panics if either key file cannot be read or parsed. Use LoadPrivateKeyECDSA and LoadPublicKeyECDSA for error handling.

Example:

privateKey, publicKey := jwt.MustLoadECDSA("private.pem", "public.pem")
token, err := jwt.Sign(jwt.ES256, privateKey, claims)
verifiedToken, err := jwt.Verify(jwt.ES256, publicKey, token)

func MustLoadEdDSA ¶

func MustLoadEdDSA(privateKeyFilename, publicKeyFilename string) (ed25519.PrivateKey, ed25519.PublicKey)

MustLoadEdDSA accepts private and public PEM filenames and returns a pair of private and public Ed25519 keys.

Pass the returned private key to Sign functions and the public key to Verify functions.

This function panics if either key file cannot be read or parsed. Use LoadPrivateKeyEdDSA and LoadPublicKeyEdDSA for error handling.

Example:

privateKey, publicKey := jwt.MustLoadEdDSA("ed25519_private.pem", "ed25519_public.pem")
token, err := jwt.Sign(jwt.EdDSA, privateKey, claims)
verifiedToken, err := jwt.Verify(jwt.EdDSA, publicKey, token)

func MustLoadHMAC ¶

func MustLoadHMAC(filenameOrRaw string) []byte

MustLoadHMAC loads an HMAC key from a file or treats the input as raw key data.

If the input is a valid file path, it reads the file contents as the key. Otherwise, it treats the input string as raw key data and converts it to []byte. This provides flexibility for both file-based and inline key configuration.

Pass the returned value to both Sign and Verify functions.

This function panics if the file cannot be read. Use LoadHMAC for error handling.

Example:

// Load from file
key := jwt.MustLoadHMAC("secret.key")

// Use raw string
key := jwt.MustLoadHMAC("my-secret-key-here")

token, err := jwt.Sign(jwt.HS256, key, claims)

func MustLoadRSA ¶

func MustLoadRSA(privateKeyFilename, publicKeyFilename string) (*rsa.PrivateKey, *rsa.PublicKey)

MustLoadRSA accepts private and public PEM file paths and returns a pair of private and public RSA keys.

Pass the returned private key to Sign functions and the public key to Verify functions.

This function panics if either key file cannot be read or parsed. Use LoadPrivateKeyRSA and LoadPublicKeyRSA for error handling.

Example:

privateKey, publicKey := jwt.MustLoadRSA("rsa_private.pem", "rsa_public.pem")
token, err := jwt.Sign(jwt.RS256, privateKey, claims)
verifiedToken, err := jwt.Verify(jwt.RS256, publicKey, token)

func ParsePrivateKeyECDSA ¶

func ParsePrivateKeyECDSA(key []byte) (*ecdsa.PrivateKey, error)

ParsePrivateKeyECDSA decodes and parses PEM-encoded ECDSA private key bytes.

The input should be PEM-encoded ECDSA private key data. This function handles the low-level parsing after PEM decoding.

Returns an error if the PEM block is missing or the key cannot be parsed. Use LoadPrivateKeyECDSA for file-based loading.

Example:

keyData := []byte("-----BEGIN EC PRIVATE KEY-----\n...")
privateKey, err := jwt.ParsePrivateKeyECDSA(keyData)

func ParsePrivateKeyEdDSA ¶

func ParsePrivateKeyEdDSA(key []byte) (ed25519.PrivateKey, error)

ParsePrivateKeyEdDSA decodes and parses PEM-encoded Ed25519 private key bytes.

The input should be PEM-encoded Ed25519 private key data in PKCS#8 format. This function handles the ASN.1 parsing to extract the seed and generate the full Ed25519 private key.

Returns an error if the PEM block is missing or the key cannot be parsed. Use LoadPrivateKeyEdDSA for file-based loading.

Example:

keyData := []byte("-----BEGIN PRIVATE KEY-----\n...")
privateKey, err := jwt.ParsePrivateKeyEdDSA(keyData)

func ParsePrivateKeyRSA ¶

func ParsePrivateKeyRSA(key []byte) (*rsa.PrivateKey, error)

ParsePrivateKeyRSA decodes and parses PEM-encoded RSA private key bytes.

The input should be PEM-encoded RSA private key data in PKCS#1 or PKCS#8 format. This function handles both formats automatically.

Returns an error if the PEM block is missing or the key cannot be parsed. Use LoadPrivateKeyRSA for file-based loading.

Example:

keyData := []byte("-----BEGIN RSA PRIVATE KEY-----\n...")
privateKey, err := jwt.ParsePrivateKeyRSA(keyData)

func ParsePublicKeyECDSA ¶

func ParsePublicKeyECDSA(key []byte) (*ecdsa.PublicKey, error)

ParsePublicKeyECDSA decodes and parses PEM-encoded ECDSA public key bytes.

The input should be PEM-encoded ECDSA public key data in PKIX format, or a certificate containing an ECDSA public key. This function handles the low-level parsing after PEM decoding.

Returns an error if the PEM block is missing or the key cannot be parsed. Use LoadPublicKeyECDSA for file-based loading.

Example:

keyData := []byte("-----BEGIN PUBLIC KEY-----\n...")
publicKey, err := jwt.ParsePublicKeyECDSA(keyData)

func ParsePublicKeyEdDSA ¶

func ParsePublicKeyEdDSA(key []byte) (ed25519.PublicKey, error)

ParsePublicKeyEdDSA decodes and parses PEM-encoded Ed25519 public key bytes.

The input should be PEM-encoded Ed25519 public key data in PKIX format. This function handles the ASN.1 parsing to extract the public key bytes.

Returns an error if the PEM block is missing or the key cannot be parsed. Use LoadPublicKeyEdDSA for file-based loading.

Example:

keyData := []byte("-----BEGIN PUBLIC KEY-----\n...")
publicKey, err := jwt.ParsePublicKeyEdDSA(keyData)

func ParsePublicKeyRSA ¶

func ParsePublicKeyRSA(key []byte) (*rsa.PublicKey, error)

ParsePublicKeyRSA decodes and parses PEM-encoded RSA public key bytes.

The input should be PEM-encoded RSA public key data in PKIX format, or a certificate containing an RSA public key. This function handles both formats automatically.

Returns an error if the PEM block is missing or the key cannot be parsed. Use LoadPublicKeyRSA for file-based loading.

Example:

keyData := []byte("-----BEGIN PUBLIC KEY-----\n...")
publicKey, err := jwt.ParsePublicKeyRSA(keyData)

func Sign ¶

func Sign(alg Alg, key PrivateKey, claims any, opts ...SignOption) ([]byte, error)

Sign creates and signs a JWT token using the specified algorithm, key, and claims.

This is the primary function for generating JWT tokens. It creates a complete JWT token by encoding the claims as the payload, applying any SignOptions for standard claims, and signing the result with the specified algorithm and key.

**Parameters**:

• alg: Cryptographic algorithm to use for signing (HS256, RS256, ES256, etc.)
• key: Private key material appropriate for the algorithm
• claims: Payload data to include in the token (any JSON-serializable type)
• opts: Optional SignOption implementations for standard claims

**Payload Security**: The claims payload is NOT encrypted by default and is base64-encoded only. Do not include sensitive information unless using encryption functions (see SignEncrypted and GCM for encrypted payloads).

**Supported Claim Types**:

• jwt.Claims struct for standard claims
• map[string]any for flexible custom claims
• Custom structs with JSON tags
• jwt.Map type alias for convenience
• Any type that marshals to valid JSON

**SignOption Processing**: When SignOptions are provided, they are processed to create standard claims which are then merged with the provided claims. Standard claims from options take precedence over conflicting claims.

**Return Value**: Returns the complete JWT token as a []byte slice in the standard format: header.payload.signature (base64url-encoded segments).

**Error Conditions**:

• Invalid algorithm or key combination
• Claims that cannot be marshaled to JSON
• SignOption processing failures
• Cryptographic signing failures

Example usage:

// Basic token with standard claims only
standardClaims := jwt.Claims{
    Subject: "user123",
    Issuer:  "myapp.com",
    Expiry:  time.Now().Add(time.Hour).Unix(),
}
token, err := jwt.Sign(jwt.HS256, secretKey, standardClaims)

// Custom claims with manual timing
now := time.Now()
customClaims := map[string]any{
    "iat":      now.Unix(),
    "exp":      now.Add(15 * time.Minute).Unix(),
    "user_id":  "12345",
    "role":     "admin",
    "permissions": []string{"read", "write"},
}
token, err := jwt.Sign(jwt.HS256, secretKey, customClaims)

// Custom claims with SignOptions for standard claims
userClaims := jwt.Map{
    "username": "john_doe",
    "role":     "user",
    "email":    "john@example.com",
}
token, err := jwt.Sign(jwt.HS256, secretKey, userClaims,
    jwt.MaxAge(15 * time.Minute),
    jwt.Audience{"api-service"},
    jwt.Claims{Issuer: "myapp.com"})

// Custom struct with embedded standard claims
type UserToken struct {
    Username string `json:"username"`
    Role     string `json:"role"`
    jwt.Claims
}
userToken := UserToken{
    Username: "alice",
    Role:     "admin",
    Claims:   jwt.Claims{Subject: "user456"},
}
token, err := jwt.Sign(jwt.RS256, rsaPrivateKey, userToken,
    jwt.MaxAge(30 * time.Minute))

See Verify for token validation and SignEncrypted for encrypted payloads.

func SignEncrypted ¶ added in v0.0.3

func SignEncrypted(alg Alg, key PrivateKey, encrypt InjectFunc, claims any, opts ...SignOption) ([]byte, error)

SignEncrypted creates and signs a JWT token with encrypted payload.

This function extends Sign by adding payload encryption capability. The claims are marshaled to JSON, then encrypted using the provided encrypt function, and finally signed. This provides confidentiality for sensitive payload data.

**Parameters**:

• alg: Cryptographic algorithm to use for signing (HS256, RS256, ES256, etc.)
• key: Private key material appropriate for the signing algorithm
• encrypt: Function to encrypt the marshaled payload (see InjectFunc)
• claims: Payload data to include in the token (any JSON-serializable type)
• opts: Optional SignOption implementations for standard claims

**Encryption Process**:

1. Claims are processed and merged with SignOptions
2. Merged claims are marshaled to JSON
3. JSON payload is encrypted using the encrypt function
4. Encrypted payload is base64url-encoded and signed

**Security Benefits**:

• Payload confidentiality (claims are encrypted)
• Protection of sensitive information in tokens
• Prevents payload inspection without decryption
• Maintains JWT structure and signature verification

**InjectFunc Signature**: The encrypt function receives []byte (marshaled claims) and returns []byte (encrypted data) and error. It's called after JSON marshaling but before base64url encoding and signing.

**Decryption**: Tokens created with SignEncrypted must be verified using VerifyEncrypted with the corresponding decrypt function.

Example usage:

// Using AES-GCM encryption (see GCM function)
encryptKey := []byte("my-32-byte-encryption-key-here!")
encrypt, decrypt := jwt.GCM(encryptKey, nil)

// Create encrypted token
sensitiveData := map[string]any{
    "ssn":           "123-45-6789",
    "credit_card":   "4111-1111-1111-1111",
    "bank_account":  "9876543210",
    "user_id":       "12345",
}

token, err := jwt.SignEncrypted(jwt.HS256, signingKey, encrypt,
    sensitiveData, jwt.MaxAge(time.Hour))

// Custom encryption function
customEncrypt := func(payload []byte) ([]byte, error) {
    // Your custom encryption logic here
    return encryptedData, nil
}

token, err := jwt.SignEncrypted(jwt.RS256, rsaKey, customEncrypt,
    userClaims, jwt.Audience{"secure-api"})

**Important Notes**:

• The encrypt function is called AFTER claims marshaling
• Both signing and encryption keys should be securely managed
• Use GCM function for authenticated encryption with AES-GCM
• Consider key rotation policies for both signing and encryption keys

See GCM for ready-to-use authenticated encryption and VerifyEncrypted for decryption and verification of encrypted tokens.

func SignEncryptedWithHeader ¶ added in v0.0.14

func SignEncryptedWithHeader(alg Alg, key PrivateKey, encrypt InjectFunc, claims any, customHeader any, opts ...SignOption) ([]byte, error)

SignEncryptedWithHeader creates and signs a JWT token with encrypted payload and custom headers.

This function combines the functionality of SignEncrypted and SignWithHeader, providing both payload encryption and custom header support in a single operation. It's ideal for scenarios requiring both payload confidentiality and header metadata.

**Parameters**:

• alg: Cryptographic algorithm to use for signing (HS256, RS256, ES256, etc.)
• key: Private key material appropriate for the signing algorithm
• encrypt: Function to encrypt the marshaled payload (see InjectFunc)
• claims: Payload data to include in the token (any JSON-serializable type)
• customHeader: Additional header fields to include (any JSON-serializable type)
• opts: Optional SignOption implementations for standard claims

**Processing Order**:

1. SignOptions are processed and merged with claims
2. Claims are marshaled to JSON
3. JSON payload is encrypted using the encrypt function
4. Custom header fields are merged with standard JWT headers
5. Token is assembled and signed with the specified algorithm

**Combined Benefits**:

• Payload confidentiality through encryption
• Header metadata for token identification and routing
• Standard claims management through SignOptions
• Complete JWT structure with signature verification

**Security Considerations**:

• Headers remain unencrypted and visible to all token bearers
• Payload is encrypted and requires decryption function to access
• Both signing and encryption keys must be securely managed
• Custom headers should not contain sensitive information

**Use Cases**:

• Multi-tenant systems with encrypted user data and tenant identification
• Key rotation systems with encrypted payloads and key identifiers
• Content-type specific tokens with encrypted sensitive data
• Audit systems requiring both data protection and metadata

Example usage:

// Multi-tenant encrypted token with key identification
encryptKey := []byte("tenant-specific-encryption-key!")
encrypt, decrypt := jwt.GCM(encryptKey, nil)

tenantHeader := map[string]any{
    "kid":       "tenant-123-key-v2",
    "tenant_id": "tenant-123",
    "env":       "production",
}

sensitiveData := map[string]any{
    "user_ssn":     "123-45-6789",
    "bank_account": "9876543210",
    "salary":       75000,
}

token, err := jwt.SignEncryptedWithHeader(jwt.RS256, rsaKey, encrypt,
    sensitiveData, tenantHeader, jwt.MaxAge(time.Hour))

// Key rotation with encrypted payload
rotationHeader := jwt.Map{
    "kid": "rotation-key-2023-q4",
    "ver": "2.0",
    "cty": "sensitive+json",
}

encryptedUserData := map[string]any{
    "personal_data": sensitiveUserInfo,
    "permissions":   userPermissions,
}

token, err := jwt.SignEncryptedWithHeader(jwt.ES256, ecdsaKey, encrypt,
    encryptedUserData, rotationHeader,
    jwt.Audience{"secure-api", "admin-panel"},
    jwt.Claims{Issuer: "auth-service"})

**Decryption and Verification**: Tokens created with this function must be verified using VerifyEncrypted with the corresponding decrypt function. Custom headers can be accessed from the returned VerifiedToken structure.

See GCM for authenticated encryption, VerifyEncrypted for token verification, and SignWithHeader for header-only customization without encryption.

func SignWithHeader ¶ added in v0.0.14

func SignWithHeader(alg Alg, key PrivateKey, claims any, customHeader any, opts ...SignOption) ([]byte, error)

SignWithHeader creates and signs a JWT token with custom header fields.

This function extends Sign by allowing custom fields to be added to the JWT header in addition to the standard "alg" and "typ" fields. Custom headers are useful for adding metadata or additional algorithm parameters.

**Parameters**:

• alg: Cryptographic algorithm to use for signing (HS256, RS256, ES256, etc.)
• key: Private key material appropriate for the signing algorithm
• claims: Payload data to include in the token (any JSON-serializable type)
• customHeader: Additional header fields to include (any JSON-serializable type)
• opts: Optional SignOption implementations for standard claims

**Header Structure**: The JWT header will contain:

• Standard fields: "alg" (algorithm), "typ" (always "JWT")
• Custom fields: Any fields from the customHeader parameter
• Conflict resolution: Custom fields override standard fields except "alg"

**Common Custom Header Use Cases**:

• "kid" (Key ID): Identifies which key was used for signing
• "x5t" (X.509 Thumbprint): Certificate thumbprint
• "jku" (JWK Set URL): URL pointing to JWK Set
• "cty" (Content Type): Content type of the secured payload
• Custom application-specific metadata

**Security Considerations**:

• Header fields are not encrypted and are visible to token bearers
• Do not include sensitive information in custom headers
• Validate custom header fields during token verification
• Be cautious with fields that could affect security decisions

Example usage:

// Token with key identifier
customHeader := map[string]any{
    "kid": "key-2023-01",
    "x5t": "dGhpcyBpcyBhIFNIQTEgdGVzdA",
}

token, err := jwt.SignWithHeader(jwt.RS256, rsaKey, userClaims,
    customHeader, jwt.MaxAge(time.Hour))

// Header with JWK Set URL
headerWithJKU := jwt.Map{
    "kid": "rsa-key-1",
    "jku": "https://myapp.com/.well-known/jwks.json",
}

token, err := jwt.SignWithHeader(jwt.RS256, rsaKey, userClaims,
    headerWithJKU, jwt.Audience{"api-service"})

// Custom content type for non-JSON payload
headerWithCty := map[string]any{
    "cty": "example-content",
    "kid": "hmac-key-1",
}

token, err := jwt.SignWithHeader(jwt.HS256, hmacKey, customPayload,
    headerWithCty, jwt.MaxAge(30 * time.Minute))

// Struct-based custom header
type CustomHeader struct {
    KeyID     string `json:"kid"`
    Algorithm string `json:"alg"` // Will be overridden by actual algorithm
    Version   string `json:"ver"`
}

header := CustomHeader{
    KeyID:   "signing-key-v2",
    Version: "2.0",
}

token, err := jwt.SignWithHeader(jwt.ES256, ecdsaKey, userClaims,
    header, jwt.Claims{Issuer: "myapp.com"})

**Header Merging**: Custom header fields are merged with standard JWT header fields. The "alg" field is always set to the specified algorithm and cannot be overridden by custom headers.

func UnmarshalWithRequired ¶

func UnmarshalWithRequired(payload []byte, dest any) error

UnmarshalWithRequired provides JSON unmarshaling with required field validation.

This function extends the standard unmarshaling behavior by validating that all fields marked with the "required" JSON tag are present and non-empty in the JWT payload. It's particularly useful for enforcing strict claim requirements in security-critical applications.

**Required Field Validation**:

• Checks struct fields tagged with `json:"fieldname,required"`
• Validates that required fields are present in the JSON payload
• Ensures required fields have non-zero values (not nil, empty string, etc.)
• Returns ErrMissingKey if any required field is missing or empty

**Usage Pattern**: Replace the global Unmarshal function to enable required field validation for all token verification operations in the application.

**Field Tag Format**: Use standard JSON tags with "required" option:

`json:"field_name,required"` - Field is required and must be present
`json:"field_name,omitempty,required"` - Cannot combine omitempty with required

**Validation Rules**:

• String fields: Must not be empty ("")
• Numeric fields: Must not be zero value (0, 0.0)
• Boolean fields: Must be explicitly set (false is valid)
• Slice/Map fields: Must not be nil or empty
• Pointer fields: Must not be nil
• Interface fields: Must not be nil

**Performance**: Adds reflection-based validation overhead after unmarshaling. Consider the performance impact for high-throughput applications.

Parameters:

• payload: Raw JSON bytes from the JWT payload
• dest: Pointer to destination struct with required field tags

Returns:

• error: JSON unmarshaling errors or ErrMissingKey for missing required fields

Example usage:

// Define claims struct with required fields
type UserClaims struct {
    Username  string    `json:"username,required"`    // Must be present and non-empty
    UserID    int       `json:"user_id,required"`     // Must be present and non-zero
    Role      string    `json:"role,required"`        // Must be present and non-empty
    Email     string    `json:"email"`                // Optional field
    IssuedAt  time.Time `json:"iat,required"`         // Must be present
}

// Enable required field validation globally
jwt.Unmarshal = jwt.UnmarshalWithRequired

// Verify token - will fail if required fields are missing
var claims UserClaims
err := jwt.Verify(jwt.HS256, secretKey, token, &claims)
if err != nil {
    // Could be ErrMissingKey if required fields are missing
    log.Printf("Token verification failed: %v", err)
}

// Token with missing required field will fail:
// {"user_id": 123, "email": "user@example.com"} // Missing username and role

// Valid token:
// {"username": "john", "user_id": 123, "role": "admin", "iat": 1609459200}