Tokens are not just data containers. They are compact cryptographic protocols that encode identity, authorization, and time constraints into a portable artifact.

This section formalizes each approach with:

• Byte-level structure
• Execution flow (generate → validate)
• Cryptographic guarantees
• Operational trade-offs

https://github.com/faustobranco/devops-db/tree/master/knowledge-base/python/tokens

1. JWT — Structured Signing Over Deterministic Input

What JWT Actually Is

JWT is a signed message format, not an encryption scheme.

It guarantees:

• Integrity
• Authenticity (if key is secret)

It does not guarantee confidentiality.

Structural Model

Generation Flow

[1] JSON Serialize
    header  -> {"alg":"HS256","typ":"JWT"}
    payload -> {"user_id":123,"exp":...}

[2] Base64URL Encode (no padding)
    encoded_header
    encoded_payload

[3] Concatenate
    signing_input = header.payload

[4] HMAC-SHA256
    signature = HMAC(secret, signing_input)

[5] Encode Signature
    base64url(signature)

[6] Final Token
    header.payload.signature

import hmac
import hashlib
import base64
import json
import time


def base64url_encode(data):
    """Encodes data to Base64URL format without padding."""
    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('utf-8')

def generate_manual_jwt(payload, secret_key):
    # 1. Header (Standard for HS256)
    header = {"alg": "HS256", "typ": "JWT"}
    encoded_header = base64url_encode(json.dumps(header).encode('utf-8'))
    
    # 2. Payload
    encoded_payload = base64url_encode(json.dumps(payload).encode('utf-8'))
    
    # 3. Signature
    signing_input = f"{encoded_header}.{encoded_payload}".encode('utf-8')
    signature = hmac.new(
        secret_key.encode('utf-8'),
        signing_input,
        hashlib.sha256
    ).digest()
    encoded_signature = base64url_encode(signature)
    
    return f"{encoded_header}.{encoded_payload}.{encoded_signature}"

def main():
    user_data = {
        "groups": "infrastructure.dns",
        "user_id": 123, 
        "zones": ["example.com"],
        "permissions": ["read", "write"],
        "iat": int(time.time()),
        "exp": int(time.time()) + 3600  # Expires in 1 hour.
    }

    # The key can be any value, but by default in these examples, I will use a 32-byte key.
    # The key was randomly generated by the function generate_secure_32_byte_key and converted to hexadecimal using convert_key_to_hex.
    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"
    print(f"JWT Token: {generate_manual_jwt(user_data, secure_key_bytes)}")

if __name__ == "__main__":
    main()    

import hmac
import hashlib
import base64
import json
import time


def base64url_encode(data):
    """Encodes data to Base64URL format without padding."""
    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('utf-8')

def generate_manual_jwt(payload, secret_key):
    # 1. Header (Standard for HS256)
    header = {"alg": "HS256", "typ": "JWT"}
    encoded_header = base64url_encode(json.dumps(header).encode('utf-8'))
    
    # 2. Payload
    encoded_payload = base64url_encode(json.dumps(payload).encode('utf-8'))
    
    # 3. Signature
    signing_input = f"{encoded_header}.{encoded_payload}".encode('utf-8')
    signature = hmac.new(
        secret_key.encode('utf-8'),
        signing_input,
        hashlib.sha256
    ).digest()
    encoded_signature = base64url_encode(signature)
    
    return f"{encoded_header}.{encoded_payload}.{encoded_signature}"

def main():
    user_data = {
        "groups": "infrastructure.dns",
        "user_id": 123, 
        "zones": ["example.com"],
        "permissions": ["read", "write"],
        "iat": int(time.time()),
        "exp": int(time.time()) + 3600  # Expires in 1 hour.
    }

    # The key can be any value, but by default in these examples, I will use a 32-byte key.
    # The key was randomly generated by the function generate_secure_32_byte_key and converted to hexadecimal using convert_key_to_hex.
    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"
    print(f"JWT Token: {generate_manual_jwt(user_data, secure_key_bytes)}")

if __name__ == "__main__":
    main()    

Validation Flow

[1] Split Token
    header | payload | signature

[2] Rebuild signing_input
    header.payload

[3] Recompute HMAC

[4] Constant-time compare
    compare_digest(expected, actual)

[5] Decode payload (ONLY after signature passes)

import hmac
import hashlib
import base64
import json
import time

def verify_manual_jwt(token, secret_key):
    try:
        header_segment, payload_segment, crypto_segment = token.split('.')
        
        # 1. Reconstruct signing input
        signing_input = f"{header_segment}.{payload_segment}".encode('utf-8')
        
        # 2. Recalculate Signature
        expected_signature = hmac.new(
            secret_key.encode('utf-8'),
            signing_input,
            hashlib.sha256
        ).digest()
        
        # 3. Secure comparison (prevents timing attacks)
        actual_signature = base64.urlsafe_b64decode(crypto_segment + "==")
        if not hmac.compare_digest(expected_signature, actual_signature):
            return None, "Invalid signature"
            
        # 4. Decode Payload
        payload_json = base64.urlsafe_b64decode(payload_segment + "==").decode('utf-8')
        return json.loads(payload_json), "Success"
        
    except Exception as e:
        return None, f"Decryption failed: {str(e)}"

def main():

    # Use the same key from the generation
    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"
    jwt_token = "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJncm91cHMiOiAiaW5mcmFzdHJ1Y3R1cmUuZG5zIiwgInVzZXJfaWQiOiAxMjMsICJ6b25lcyI6IFsiZXhhbXBsZS5jb20iXSwgInBlcm1pc3Npb25zIjogWyJyZWFkIiwgIndyaXRlIl0sICJpYXQiOiAxNzc0ODU4OTA3LCAiZXhwIjogMTc3NDg2MjUwN30.X4FtXt-4MAVIjJ96gLFqoJmzvGyuCzqBRyw5CBEeb6k"

    # 2. Decode
    decoded_data, status = verify_manual_jwt(jwt_token, secure_key_bytes)
    print(f"Status: {status}")
    print(f"Decoded Data: {decoded_data}")


if __name__ == "__main__":
    main()    

import hmac
import hashlib
import base64
import json
import time

def verify_manual_jwt(token, secret_key):
    try:
        header_segment, payload_segment, crypto_segment = token.split('.')
        
        # 1. Reconstruct signing input
        signing_input = f"{header_segment}.{payload_segment}".encode('utf-8')
        
        # 2. Recalculate Signature
        expected_signature = hmac.new(
            secret_key.encode('utf-8'),
            signing_input,
            hashlib.sha256
        ).digest()
        
        # 3. Secure comparison (prevents timing attacks)
        actual_signature = base64.urlsafe_b64decode(crypto_segment + "==")
        if not hmac.compare_digest(expected_signature, actual_signature):
            return None, "Invalid signature"
            
        # 4. Decode Payload
        payload_json = base64.urlsafe_b64decode(payload_segment + "==").decode('utf-8')
        return json.loads(payload_json), "Success"
        
    except Exception as e:
        return None, f"Decryption failed: {str(e)}"

def main():

    # Use the same key from the generation
    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"
    jwt_token = "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJncm91cHMiOiAiaW5mcmFzdHJ1Y3R1cmUuZG5zIiwgInVzZXJfaWQiOiAxMjMsICJ6b25lcyI6IFsiZXhhbXBsZS5jb20iXSwgInBlcm1pc3Npb25zIjogWyJyZWFkIiwgIndyaXRlIl0sICJpYXQiOiAxNzc0ODU4OTA3LCAiZXhwIjogMTc3NDg2MjUwN30.X4FtXt-4MAVIjJ96gLFqoJmzvGyuCzqBRyw5CBEeb6k"

    # 2. Decode
    decoded_data, status = verify_manual_jwt(jwt_token, secure_key_bytes)
    print(f"Status: {status}")
    print(f"Decoded Data: {decoded_data}")


if __name__ == "__main__":
    main()    

python3 create.py
JWT Token: eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJncm91cHMiOiAiaW5mcmFzdHJ1Y3R1cmUuZG5zIiwgInVzZXJfaWQiOiAxMjMsICJ6b25lcyI6IFsiZXhhbXBsZS5jb20iXSwgInBlcm1pc3Npb25zIjogWyJyZWFkIiwgIndyaXRlIl0sICJpYXQiOiAxNzc0ODU4OTA3LCAiZXhwIjogMTc3NDg2MjUwN30.X4FtXt-4MAVIjJ96gLFqoJmzvGyuCzqBRyw5CBEeb6k

python3 validation.py
Status: Success
Decoded Data: {'groups': 'infrastructure.dns', 'user_id': 123, 'zones': ['example.com'], 'permissions': ['read', 'write'], 'iat': 1774858907, 'exp': 1774862507}

python3 create.py
JWT Token: eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJncm91cHMiOiAiaW5mcmFzdHJ1Y3R1cmUuZG5zIiwgInVzZXJfaWQiOiAxMjMsICJ6b25lcyI6IFsiZXhhbXBsZS5jb20iXSwgInBlcm1pc3Npb25zIjogWyJyZWFkIiwgIndyaXRlIl0sICJpYXQiOiAxNzc0ODU4OTA3LCAiZXhwIjogMTc3NDg2MjUwN30.X4FtXt-4MAVIjJ96gLFqoJmzvGyuCzqBRyw5CBEeb6k

python3 validation.py
Status: Success
Decoded Data: {'groups': 'infrastructure.dns', 'user_id': 123, 'zones': ['example.com'], 'permissions': ['read', 'write'], 'iat': 1774858907, 'exp': 1774862507}

Critical Observations

• Order matters → any serialization change breaks signature
• Payload is readable → Base64 ≠ encryption
• No early rejection → must process entire token first

Advantages

• Extremely interoperable
• Stateless validation
• Simple to implement and debug
• Works across heterogeneous systems

Disadvantages (Real, Not Theoretical)

• High misconfiguration risk (alg confusion)
• No confidentiality
• Requires full parsing before validation
• Weak key usage is common

2. PASETO — Encrypted Tokens with Fixed Cryptographic Rules

What PASETO Actually Is

PASETO is a versioned cryptographic protocol, not just a format.

It enforces:

• Fixed algorithms
• Safe defaults
• No developer choice in crypto primitives

Structural Model

Generation Flow

[1] Serialize payload → JSON → bytes

[2] Generate nonce (12B in your impl)
    nonce = os.urandom(12)

[3] AEAD Encrypt
    cipher = encrypt(
        nonce,
        payload,
        AAD = header ("v4.local.")
    )

[4] Encode
    token = "v4.local." + base64url(nonce + cipher)

import os
import time
import json         
import base64
from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305

def convert_hex_to_key(hex_string):
    """
    Decodes a 64-character hexadecimal string back into 32 bytes.
    Validates length to ensure cryptographic integrity before use.
    """
    try:
        key_bytes = bytes.fromhex(hex_string)
        if len(key_bytes) != 32:
            raise ValueError("Invalid key length: Must be exactly 32 bytes.")
        return key_bytes
    except ValueError as e:
        print(f"Key Conversion Error: {e}")
        return None

def base64url_encode(data):
    """Encodes data to Base64URL format without padding."""
    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('utf-8')


def generate_paseto_v4_local(payload, key_32_bytes):
    # Header for v4.local
    header = b"v4.local."
    
    # Payload must be bytes (usually JSON)
    plain_text = json.dumps(payload).encode('utf-8')
    
    # Nonce (Adjusted to 12 bytes to match the available AEAD class)
    nonce = os.urandom(12)
    
    # Initialize Cipher using the compatible ChaCha20Poly1305
    aead = ChaCha20Poly1305(key_32_bytes)
    
    # The header acts as 'Additional Authenticated Data' (AAD)
    # This ensures the header cannot be tampered with
    cipher_text = aead.encrypt(nonce, plain_text, header)
    
    # Format: header + base64(nonce + cipher_text)
    token_body = base64url_encode(nonce + cipher_text)
    return f"v4.local.{token_body}"

# Usage (Requires a 32-byte key)

def main():
    user_data = {
        "groups": "infrastructure.dns",
        "user_id": 123, 
        "zones": ["example.com"],
        "permissions": ["read", "write"],
        "iat": int(time.time()),
        "exp": int(time.time()) + 3600  # Expires in 1 hour.
    }

    # The key MUST be exactly 32 bytes
    # The key was randomly generated by the function generate_secure_32_byte_key and converted to hexadecimal using convert_key_to_hex.

    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"

    print(f"Paseto Token: {generate_paseto_v4_local(user_data, convert_hex_to_key(secure_key_bytes))}")


if __name__ == "__main__":
    main()    

import os
import time
import json         
import base64
from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305

def convert_hex_to_key(hex_string):
    """
    Decodes a 64-character hexadecimal string back into 32 bytes.
    Validates length to ensure cryptographic integrity before use.
    """
    try:
        key_bytes = bytes.fromhex(hex_string)
        if len(key_bytes) != 32:
            raise ValueError("Invalid key length: Must be exactly 32 bytes.")
        return key_bytes
    except ValueError as e:
        print(f"Key Conversion Error: {e}")
        return None

def base64url_encode(data):
    """Encodes data to Base64URL format without padding."""
    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('utf-8')


def generate_paseto_v4_local(payload, key_32_bytes):
    # Header for v4.local
    header = b"v4.local."
    
    # Payload must be bytes (usually JSON)
    plain_text = json.dumps(payload).encode('utf-8')
    
    # Nonce (Adjusted to 12 bytes to match the available AEAD class)
    nonce = os.urandom(12)
    
    # Initialize Cipher using the compatible ChaCha20Poly1305
    aead = ChaCha20Poly1305(key_32_bytes)
    
    # The header acts as 'Additional Authenticated Data' (AAD)
    # This ensures the header cannot be tampered with
    cipher_text = aead.encrypt(nonce, plain_text, header)
    
    # Format: header + base64(nonce + cipher_text)
    token_body = base64url_encode(nonce + cipher_text)
    return f"v4.local.{token_body}"

# Usage (Requires a 32-byte key)

def main():
    user_data = {
        "groups": "infrastructure.dns",
        "user_id": 123, 
        "zones": ["example.com"],
        "permissions": ["read", "write"],
        "iat": int(time.time()),
        "exp": int(time.time()) + 3600  # Expires in 1 hour.
    }

    # The key MUST be exactly 32 bytes
    # The key was randomly generated by the function generate_secure_32_byte_key and converted to hexadecimal using convert_key_to_hex.

    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"

    print(f"Paseto Token: {generate_paseto_v4_local(user_data, convert_hex_to_key(secure_key_bytes))}")


if __name__ == "__main__":
    main()    

Validation Flow

[1] Validate header prefix
    must start with "v4.local."

[2] Decode base64
    extract nonce + ciphertext

[3] AEAD Decrypt
    decrypt(nonce, ciphertext, AAD=header)
    IF ANYTHING FAILS → reject

[4] Parse JSON payload

import os
import time
import json         
import base64
from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305

def convert_hex_to_key(hex_string):
    """
    Decodes a 64-character hexadecimal string back into 32 bytes.
    Validates length to ensure cryptographic integrity before use.
    """
    try:
        key_bytes = bytes.fromhex(hex_string)
        if len(key_bytes) != 32:
            raise ValueError("Invalid key length: Must be exactly 32 bytes.")
        return key_bytes
    except ValueError as e:
        print(f"Key Conversion Error: {e}")
        return None


def decrypt_paseto_v4_local(token, key_32_bytes):
    try:
        header = b"v4.local."
        if not token.startswith("v4.local."):
            return None, "Invalid header"
            
        # Remove header and decode body
        encoded_body = token.replace("v4.local.", "")
        # O Base64URL do Python às vezes precisa de padding manual se não for o standard original
        body = base64.urlsafe_b64decode(encoded_body + "===")
        
        # AJUSTE EVOLUTIVO: Extrair 12 bytes de Nonce (conforme o gerador)
        nonce = body[:12]
        cipher_text = body[12:]
        
        # Usar a mesma classe do gerador
        aead = ChaCha20Poly1305(key_32_bytes)
        
        # Decrypt usando header como AAD
        decrypted_bytes = aead.decrypt(nonce, cipher_text, header)
        return json.loads(decrypted_bytes.decode('utf-8')), "Success"
        
    except Exception as e:
        # Debug opcional: print(f"Erro real: {e}")
        return None, "Decryption failed (Tampered or wrong key)"

def main():
    
    # Use the same key from the generation    
    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"
    paseto_token = "v4.local.kobZTk0C8p0UuVAR_XeaJqpXdM8lbg2K6IYp6nd4lX2JyiO-2369cNwsMJoJuNBGxUGGD6_i4Qo5oWJv2-bl0r8lBBEPVr8bYeTV_w1Bc2pZtTr_yXhUslsPj1lbBAwIra6A3n12GoDIEfw5AKR5hEh_O0dz-6xgACVhaRYKlt5QT6TI8j0Bw-Ac7N5_6gsNsCwvWQdiaAfmy151JCILbIwf5NvnwfRj5tqjdZ0L"

    # 2. Decode
    data, status = decrypt_paseto_v4_local(paseto_token, convert_hex_to_key(secure_key_bytes))
    print(f"Status: {status}")
    print(f"Decoded Data: {data}")

if __name__ == "__main__":
    main()    

import os
import time
import json         
import base64
from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305

def convert_hex_to_key(hex_string):
    """
    Decodes a 64-character hexadecimal string back into 32 bytes.
    Validates length to ensure cryptographic integrity before use.
    """
    try:
        key_bytes = bytes.fromhex(hex_string)
        if len(key_bytes) != 32:
            raise ValueError("Invalid key length: Must be exactly 32 bytes.")
        return key_bytes
    except ValueError as e:
        print(f"Key Conversion Error: {e}")
        return None


def decrypt_paseto_v4_local(token, key_32_bytes):
    try:
        header = b"v4.local."
        if not token.startswith("v4.local."):
            return None, "Invalid header"
            
        # Remove header and decode body
        encoded_body = token.replace("v4.local.", "")
        # O Base64URL do Python às vezes precisa de padding manual se não for o standard original
        body = base64.urlsafe_b64decode(encoded_body + "===")
        
        # AJUSTE EVOLUTIVO: Extrair 12 bytes de Nonce (conforme o gerador)
        nonce = body[:12]
        cipher_text = body[12:]
        
        # Usar a mesma classe do gerador
        aead = ChaCha20Poly1305(key_32_bytes)
        
        # Decrypt usando header como AAD
        decrypted_bytes = aead.decrypt(nonce, cipher_text, header)
        return json.loads(decrypted_bytes.decode('utf-8')), "Success"
        
    except Exception as e:
        # Debug opcional: print(f"Erro real: {e}")
        return None, "Decryption failed (Tampered or wrong key)"

def main():
    
    # Use the same key from the generation    
    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"
    paseto_token = "v4.local.kobZTk0C8p0UuVAR_XeaJqpXdM8lbg2K6IYp6nd4lX2JyiO-2369cNwsMJoJuNBGxUGGD6_i4Qo5oWJv2-bl0r8lBBEPVr8bYeTV_w1Bc2pZtTr_yXhUslsPj1lbBAwIra6A3n12GoDIEfw5AKR5hEh_O0dz-6xgACVhaRYKlt5QT6TI8j0Bw-Ac7N5_6gsNsCwvWQdiaAfmy151JCILbIwf5NvnwfRj5tqjdZ0L"

    # 2. Decode
    data, status = decrypt_paseto_v4_local(paseto_token, convert_hex_to_key(secure_key_bytes))
    print(f"Status: {status}")
    print(f"Decoded Data: {data}")

if __name__ == "__main__":
    main()    

python3 create.py
Paseto Token: v4.local.kobZTk0C8p0UuVAR_XeaJqpXdM8lbg2K6IYp6nd4lX2JyiO-2369cNwsMJoJuNBGxUGGD6_i4Qo5oWJv2-bl0r8lBBEPVr8bYeTV_w1Bc2pZtTr_yXhUslsPj1lbBAwIra6A3n12GoDIEfw5AKR5hEh_O0dz-6xgACVhaRYKlt5QT6TI8j0Bw-Ac7N5_6gsNsCwvWQdiaAfmy151JCILbIwf5NvnwfRj5tqjdZ0L

python3 validation.py
Status: Success
Decoded Data: {'groups': 'infrastructure.dns', 'user_id': 123, 'zones': ['example.com'], 'permissions': ['read', 'write'], 'iat': 1774859460, 'exp': 1774863060}

python3 create.py
Paseto Token: v4.local.kobZTk0C8p0UuVAR_XeaJqpXdM8lbg2K6IYp6nd4lX2JyiO-2369cNwsMJoJuNBGxUGGD6_i4Qo5oWJv2-bl0r8lBBEPVr8bYeTV_w1Bc2pZtTr_yXhUslsPj1lbBAwIra6A3n12GoDIEfw5AKR5hEh_O0dz-6xgACVhaRYKlt5QT6TI8j0Bw-Ac7N5_6gsNsCwvWQdiaAfmy151JCILbIwf5NvnwfRj5tqjdZ0L

python3 validation.py
Status: Success
Decoded Data: {'groups': 'infrastructure.dns', 'user_id': 123, 'zones': ['example.com'], 'permissions': ['read', 'write'], 'iat': 1774859460, 'exp': 1774863060}

Critical Observations

• Header is cryptographically bound (AAD)
• Single-step validation (decrypt = verify)
• No partial trust state

Advantages

• Secure-by-default (no algorithm selection)
• Payload confidentiality
• Strong cryptographic guarantees (AEAD)
• Resistant to developer mistakes

Disadvantages

• Requires 32-byte keys (operational overhead)
• Slightly larger tokens than Branca
• No early expiration check (must decrypt first)
• Less ecosystem support than JWT

Important Implementation Note

Your version uses:

nonce = 12 bytes (ChaCha20-Poly1305)

Instead of:

24 bytes (XChaCha20)

Trade-off:

• ✅ Compatible with standard libraries
• ❌ Lower misuse resistance (nonce reuse risk)

3. Branca — Binary Token Protocol Optimized for Throughput

What Branca Actually Is

Branca is a binary token protocol with embedded validation primitives.

It is designed for:

• Minimal overhead
• Early rejection
• High-throughput systems

Structural Model

(Base64URL encoded at the end)

(From )

Generation Flow

[1] Serialize payload → JSON → bytes

[2] Generate timestamp
    timestamp = uint32(time)

[3] Generate nonce (12B)

[4] Build AAD
    AAD = version + timestamp + nonce

[5] Encrypt
    cipher = AEAD.encrypt(nonce, payload, AAD)

[6] Assemble binary token
    token = version + timestamp + nonce + cipher

[7] Base64URL encode

import struct
import time
import os
import json
import base64   
from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305

def convert_hex_to_key(hex_string):
    """
    Decodes a 64-character hexadecimal string back into 32 bytes.
    Validates length to ensure cryptographic integrity before use.
    """
    try:
        key_bytes = bytes.fromhex(hex_string)
        if len(key_bytes) != 32:
            raise ValueError("Invalid key length: Must be exactly 32 bytes.")
        return key_bytes
    except ValueError as e:
        print(f"Key Conversion Error: {e}")
        return None
def generate_branca_token(payload, key_32_bytes):
    version = b'\xBA' 
    
    timestamp = struct.pack(">I", int(time.time())) 
    
    nonce = os.urandom(12) 
    
    plain_text = json.dumps(payload).encode('utf-8')
    
    aead = ChaCha20Poly1305(key_32_bytes)
    
    associated_data = version + timestamp + nonce
    
    cipher_text = aead.encrypt(nonce, plain_text, associated_data)
    
    binary_token = version + timestamp + nonce + cipher_text
    
    return base64.urlsafe_b64encode(binary_token).decode('utf-8')


def main():
    user_data = {
        "groups": "infrastructure.dns",
        "user_id": 123, 
        "zones": ["example.com"],
        "permissions": ["read", "write"],
        "iat": int(time.time()),
        "exp": int(time.time()) + 3600  # Expires in 1 hour.
    }

    # The key MUST be exactly 32 bytes
    # The key was randomly generated by the function generate_secure_32_byte_key and converted to hexadecimal using convert_key_to_hex.

    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"
    token = generate_branca_token(user_data, convert_hex_to_key(secure_key_bytes))
    print(f"Branca Token: {token}")

if __name__ == "__main__":
    main()    

import struct
import time
import os
import json
import base64   
from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305

def convert_hex_to_key(hex_string):
    """
    Decodes a 64-character hexadecimal string back into 32 bytes.
    Validates length to ensure cryptographic integrity before use.
    """
    try:
        key_bytes = bytes.fromhex(hex_string)
        if len(key_bytes) != 32:
            raise ValueError("Invalid key length: Must be exactly 32 bytes.")
        return key_bytes
    except ValueError as e:
        print(f"Key Conversion Error: {e}")
        return None
def generate_branca_token(payload, key_32_bytes):
    version = b'\xBA' 
    
    timestamp = struct.pack(">I", int(time.time())) 
    
    nonce = os.urandom(12) 
    
    plain_text = json.dumps(payload).encode('utf-8')
    
    aead = ChaCha20Poly1305(key_32_bytes)
    
    associated_data = version + timestamp + nonce
    
    cipher_text = aead.encrypt(nonce, plain_text, associated_data)
    
    binary_token = version + timestamp + nonce + cipher_text
    
    return base64.urlsafe_b64encode(binary_token).decode('utf-8')


def main():
    user_data = {
        "groups": "infrastructure.dns",
        "user_id": 123, 
        "zones": ["example.com"],
        "permissions": ["read", "write"],
        "iat": int(time.time()),
        "exp": int(time.time()) + 3600  # Expires in 1 hour.
    }

    # The key MUST be exactly 32 bytes
    # The key was randomly generated by the function generate_secure_32_byte_key and converted to hexadecimal using convert_key_to_hex.

    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"
    token = generate_branca_token(user_data, convert_hex_to_key(secure_key_bytes))
    print(f"Branca Token: {token}")

if __name__ == "__main__":
    main()    

Validation Flow (Highly Optimized)

[1] Base64 decode → binary

[2] Extract fields
    version | timestamp | nonce | ciphertext

[3] Version check
    if != 0xBA → reject

[4] TTL validation (NO DECRYPTION)
    if now - timestamp > TTL → reject

[5] Rebuild AAD
    version + timestamp + nonce

[6] AEAD decrypt
    decrypt(nonce, ciphertext, AAD)

[7] Parse JSON

import struct
import time
import os
import json
import base64   
from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305

def convert_hex_to_key(hex_string):
    """
    Decodes a 64-character hexadecimal string back into 32 bytes.
    Validates length to ensure cryptographic integrity before use.
    """
    try:
        key_bytes = bytes.fromhex(hex_string)
        if len(key_bytes) != 32:
            raise ValueError("Invalid key length: Must be exactly 32 bytes.")
        return key_bytes
    except ValueError as e:
        print(f"Key Conversion Error: {e}")
        return None


def decode_branca_token(token, key_32_bytes, ttl_seconds=3600):
    try:
        # 1. Decode Base64URL to Binary
        binary_token = base64.urlsafe_b64decode(token + "==")
        
        # 2. Extract Parts (Following the exact positions used in generate)
        # Version (1B) | Timestamp (4B) | Nonce (12B) | Ciphertext (nB)
        version = binary_token[0:1]
        timestamp_bytes = binary_token[1:5]
        nonce = binary_token[5:17] 
        cipher_text = binary_token[17:]
        
        # 3. Validation: Version check
        if version != b'\xBA':
            return None, "Error: Unsupported version"
            
        # 4. Validation: Expiration (TTL)
        token_time = struct.unpack(">I", timestamp_bytes)[0]
        if int(time.time()) - token_time > ttl_seconds:
            return None, "Error: Token has expired"
            
        # 5. Initialize AEAD
        aead = ChaCha20Poly1305(key_32_bytes)
        
        # 6. Reconstruct AAD (Must be exactly as it was during encryption)
        associated_data = version + timestamp_bytes + nonce
        
        # 7. Decrypt and Verify
        # If the key is wrong or the token was tampered with, this will fail
        decrypted_payload = aead.decrypt(nonce, cipher_text, associated_data)
        
        return json.loads(decrypted_payload.decode('utf-8')), "Success"
        
    except Exception as e:
        return None, f"Decryption failed: {str(e)}"

def main():

    # Use the same key from the generation
    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"
    token = "umnKM7Cwf3KvbI5zPXAbo8Dt-1hBWl414wO8Skz8Z3nQoDeaaV88Gh9aIohZY2w7Eo9eUqtr2ULPOJ7dEeQ9k5Ybmg4-2J5gYe_xV2QUOFBlfelYGRJV8W9fCtxQkEfsFj4dEaULujo5puMdoSkGQnR8bpTPSZnx2-xuLOO0XhKzbtq-1MFSmTfAfIA3OCwgm6YZHIVkShIe4VZEGEfMyF4ydIoxHimTGD-eCZXoTQOzsn0="

    # 2. Decode
    decoded_data, status = decode_branca_token(token, convert_hex_to_key(secure_key_bytes))
    print(f"Status: {status}")
    print(f"Decoded Data: {decoded_data}")

if __name__ == "__main__":
    main()        

import struct
import time
import os
import json
import base64   
from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305

def convert_hex_to_key(hex_string):
    """
    Decodes a 64-character hexadecimal string back into 32 bytes.
    Validates length to ensure cryptographic integrity before use.
    """
    try:
        key_bytes = bytes.fromhex(hex_string)
        if len(key_bytes) != 32:
            raise ValueError("Invalid key length: Must be exactly 32 bytes.")
        return key_bytes
    except ValueError as e:
        print(f"Key Conversion Error: {e}")
        return None


def decode_branca_token(token, key_32_bytes, ttl_seconds=3600):
    try:
        # 1. Decode Base64URL to Binary
        binary_token = base64.urlsafe_b64decode(token + "==")
        
        # 2. Extract Parts (Following the exact positions used in generate)
        # Version (1B) | Timestamp (4B) | Nonce (12B) | Ciphertext (nB)
        version = binary_token[0:1]
        timestamp_bytes = binary_token[1:5]
        nonce = binary_token[5:17] 
        cipher_text = binary_token[17:]
        
        # 3. Validation: Version check
        if version != b'\xBA':
            return None, "Error: Unsupported version"
            
        # 4. Validation: Expiration (TTL)
        token_time = struct.unpack(">I", timestamp_bytes)[0]
        if int(time.time()) - token_time > ttl_seconds:
            return None, "Error: Token has expired"
            
        # 5. Initialize AEAD
        aead = ChaCha20Poly1305(key_32_bytes)
        
        # 6. Reconstruct AAD (Must be exactly as it was during encryption)
        associated_data = version + timestamp_bytes + nonce
        
        # 7. Decrypt and Verify
        # If the key is wrong or the token was tampered with, this will fail
        decrypted_payload = aead.decrypt(nonce, cipher_text, associated_data)
        
        return json.loads(decrypted_payload.decode('utf-8')), "Success"
        
    except Exception as e:
        return None, f"Decryption failed: {str(e)}"

def main():

    # Use the same key from the generation
    secure_key_bytes = "6242a422c9964c48ea61bc11ba412ad7a7e96cb1a548af3dc25ca9cdb3a2f0a2"
    token = "umnKM7Cwf3KvbI5zPXAbo8Dt-1hBWl414wO8Skz8Z3nQoDeaaV88Gh9aIohZY2w7Eo9eUqtr2ULPOJ7dEeQ9k5Ybmg4-2J5gYe_xV2QUOFBlfelYGRJV8W9fCtxQkEfsFj4dEaULujo5puMdoSkGQnR8bpTPSZnx2-xuLOO0XhKzbtq-1MFSmTfAfIA3OCwgm6YZHIVkShIe4VZEGEfMyF4ydIoxHimTGD-eCZXoTQOzsn0="

    # 2. Decode
    decoded_data, status = decode_branca_token(token, convert_hex_to_key(secure_key_bytes))
    print(f"Status: {status}")
    print(f"Decoded Data: {decoded_data}")

if __name__ == "__main__":
    main()        

python3 create.py
Branca Token: umnKM7Cwf3KvbI5zPXAbo8Dt-1hBWl414wO8Skz8Z3nQoDeaaV88Gh9aIohZY2w7Eo9eUqtr2ULPOJ7dEeQ9k5Ybmg4-2J5gYe_xV2QUOFBlfelYGRJV8W9fCtxQkEfsFj4dEaULujo5puMdoSkGQnR8bpTPSZnx2-xuLOO0XhKzbtq-1MFSmTfAfIA3OCwgm6YZHIVkShIe4VZEGEfMyF4ydIoxHimTGD-eCZXoTQOzsn0=

python3 validation.py
Status: Success
Decoded Data: {'groups': 'infrastructure.dns', 'user_id': 123, 'zones': ['example.com'], 'permissions': ['read', 'write'], 'iat': 1774859184, 'exp': 1774862784}

python3 create.py
Branca Token: umnKM7Cwf3KvbI5zPXAbo8Dt-1hBWl414wO8Skz8Z3nQoDeaaV88Gh9aIohZY2w7Eo9eUqtr2ULPOJ7dEeQ9k5Ybmg4-2J5gYe_xV2QUOFBlfelYGRJV8W9fCtxQkEfsFj4dEaULujo5puMdoSkGQnR8bpTPSZnx2-xuLOO0XhKzbtq-1MFSmTfAfIA3OCwgm6YZHIVkShIe4VZEGEfMyF4ydIoxHimTGD-eCZXoTQOzsn0=

python3 validation.py
Status: Success
Decoded Data: {'groups': 'infrastructure.dns', 'user_id': 123, 'zones': ['example.com'], 'permissions': ['read', 'write'], 'iat': 1774859184, 'exp': 1774862784}

After 1 hour

python3 validation.py
Status: Error: Token has expired
Decoded Data: None

python3 validation.py
Status: Error: Token has expired
Decoded Data: None

Critical Optimization Insight

EXPIRATION CHECK HAPPENS BEFORE DECRYPTION

This is unique.

Advantages

• Extremely compact (binary format)
• Early rejection → CPU efficient
• Always encrypted (no unsafe mode)
• Ideal for high-throughput systems

Disadvantages

• Not human-readable (debugging harder)
• Less standardized ecosystem
• Requires strict key management
• Less flexible metadata handling

Cross-System Flow Comparison

Validation Cost Pipeline

JWT:
  decode → verify signature → parse → check expPASETO:
  decode → decrypt (verify + integrity) → parse → check expBranca:
  decode → extract header → check exp → decrypt → parse

Security vs Performance Trade-off

(Not absolute — contextual)

Key Insight: Where Systems Actually Differ

Trust Boundary Location

• JWT → after signature validation
• PASETO → after decryption
• Branca → partially before decryption (timestamp)

Failure Modes

CPU Cost Distribution

• JWT → low crypto, high parsing
• PASETO → crypto-heavy
• Branca → optimized pipeline

Aqui tens os complementos detalhados para o teu artigo, estruturados com uma linguagem técnica rigorosa e prontos a serem inseridos como capítulos ou secções de “Deep Dive”.

The Pillars of Modern Token Security

1. The Nonce: The Entropy Injector

The Nonce (Number used once) is the critical component that prevents Replay Attacks. In cryptographic protocols like PASETO and Branca, the nonce ensures that encrypting the exact same payload twice results in two completely different tokens.

• How it works: It is a unique value combined with the 32-byte key during encryption. Even if the key is static, the ever-changing nonce creates a unique ciphertext.
• PASETO v4 (XChaCha20): Uses a 24-byte (192-bit) nonce. This “extended” size is so massive that the probability of generating the same nonce twice (collision) is mathematically negligible, even in distributed systems generating billions of tokens.
• Branca (ChaCha20): Uses a 12-byte (96-bit) nonce, focusing on binary compactness while maintaining high security.

2. The KID (Key ID): The Strategic Navigator

The KID is a non-secret metadata field (usually placed in the Footer) that acts as a pointer. It tells the server exactly which key to use to decrypt the token.

• Seamless Key Rotation: Without a KID, rotating keys forces all users to log out. With a KID, the server can identify if a token was signed with key_v1 or key_v2, allowing for a graceful transition period.
• Multi-Tenancy & Isolation: It allows the system to store unique 32-byte keys for millions of different users. The server reads the KID, fetches the specific key from a high-speed cache (like Redis), and performs the validation.
• Efficiency: It eliminates “trial-and-error” decryption, where a server would otherwise have to try every key in its database to open a single token.

Metadata Architecture: Implementing the Key ID (KID)

The Key ID (KID) is the essential metadata that allows a service to scale. It acts as a pointer, telling the authentication layer exactly which 32-byte key to retrieve from the database or cache (like Redis) before attempting decryption. However, the placement of this ID varies significantly across different token standards.

JSON Web Tokens (JWT): The Native Header Field

In the JWT ecosystem, the kid is a standard field defined by the JOSE (JSON Object Signing and Encryption) specifications.

• Placement: Inside the Header (the first segment of the token).
• Mechanism: The header is a non-encrypted JSON object encoded in Base64URL.
• Workflow: The server decodes the header string, parses the JSON to find the "kid": "..." value, fetches the corresponding key, and then proceeds to verify the signature.
• Security Note: While the header is visible, it is protected by the final signature. If an attacker modifies the kid to force the use of a different key, the cryptographic signature will fail to validate.

PASETO: The Authenticated Footer

PASETO (Platform-Agnostic Security Tokens) avoids placing metadata in the header to keep the protocol identification (v4.local.) clean. Instead, it introduces the Footer.

• Placement: The Footer (the third segment, appended after the ciphertext).
• Mechanism: Like the header in JWT, the footer is Base64URL encoded but not encrypted.
• Workflow: The server extracts the footer to identify the key version or user ID.
• The Security Advantage: In PASETO, the footer is part of the Authenticated Data (AAD). This means the footer bytes are cryptographically “bound” to the encrypted body. If the kid in the footer is altered by a single bit, the decryption of the main body will mathematically fail. It provides identity integrity without needing to decrypt the payload first.

Branca: The Manual Envelope (Prefixing)

Branca follows a “Secret-Only” philosophy. It is a binary format that does not natively support an unencrypted metadata field like a footer or a header.

• Placement: Requires a Manual Envelope or Prefix.
• Mechanism: Since the Branca payload is opaque until decrypted, the kid must be prepended to the token string, often separated by a delimiter (e.g., . or _).
• Workflow: The implementation logic must split the string: [KID].[BRANCA_TOKEN]. The server uses the first part to find the key and the second part for the actual cryptographic operation.
• Architectural Trade-off: While this adds a step to the implementation, it keeps the Branca token itself extremely compact and focused purely on the encrypted payload.

Comparative Metadata Strategy

Exportar para Sheets

Conclusion for Architects

When designing for scale, the PASETO Footer offers the most elegant solution. It allows the server to perform a high-speed “Key Lookup” using the kid while ensuring that the metadata itself is tamper-proof. This architecture enables seamless Key Rotation and User Isolation without the overhead of trial-and-error decryption.

3. Steganography & Protocol Obfuscation

While 256-bit encryption provides the mathematical foundation of our security, Protocol Obfuscation adds a layer of “Security by Obscurity” that hardens the infrastructure against targeted reconnaissance. By masking the predictable fingerprints of standard tokens, we transition from a static target to a Moving Target Defense.

Concatenation Strategies (Prefixing)

Instead of transmitting raw cryptographic tokens, we wrap them with a custom identifier known as a shibboleth—a specific sequence used to distinguish authorized traffic at the edge.

• Transparent JWT: eyJhbG... → Obfuscated: auth_v2_eyJhbG...
• Raw Branca: 8J+S... → Ofuscado: internal_8J+S...
• PASETO v4: v4.local.ABC → Ofuscado: sec_v4_ABC

The “Header Swap” & Pattern Masking Process

This is the most aggressive form of obfuscation. It involves stripping the protocol’s identifiable header and replacing it with a proprietary value. This prevents automated scanners from identifying the cryptographic standard in use.

A. JWT (The JSON Pattern)

• The Signature: A standard JWT almost always begins with eyJ (Base64 for {").
• The Swap: The server replaces eyJ with a custom string like XKT.
• Result: Scanners looking for the common eyJ pattern will ignore the token as “noise.”

B. PASETO (The Versioning Pattern)

• The Signature: PASETO tokens explicitly start with their version and purpose, such as v4.local.. This is a massive “fingerprint” for attackers.
• The Swap: You can strip the v4.local. prefix entirely and replace it with a shorter, non-descript tag like k9_.
• The “Unswap”: Upon Ingress, the server recognizes the k9_ tag and prepends the v4.local. string back to the token before passing it to the PASETO library for decryption.

C. Branca (The Base62 Pattern)

• The Signature: Branca tokens are often recognizable by their specific character set (Base62) and fixed-length headers. While they don’t have a text prefix like PASETO, their “look” is distinct.
• The Obfuscation: Since Branca is a binary-to-text format, you can apply a simple XOR mask or a Character Mapping to the first few characters.
• Example: If a Branca token starts with 8J..., your egress layer swaps those specific characters for a custom sequence. It hides the fact that you are using a 12-byte nonce/timestamp structure.

Advantages of Universal Obfuscation (Expanded)

• Infrastructure Blindness: It prevents WAFs (Web Application Firewalls) or malicious actors from identifying the exact technology stack. If the technology (e.g., “This service is running Branca v0.8”) remains unidentified, the cost of orchestrating a targeted attack increases exponentially.
• Zero-Day Exploit Shielding: Should a critical vulnerability be discovered in a specific PASETO or JWT library, your tokens will not be automated targets for scripts scanning the network for strings like v4.local. or eyJ.
• Payload Minimization: By swapping a long header like v4.local. (9 characters) with a 2-character tag like _z, you save bytes in every single HTTP request, improving performance at extreme scales.
• Version Control & Intelligent Routing: Custom prefixes allow Load Balancers or API Gateways to route requests to specific service versions (e.g., v1_... vs v2_...) without the overhead of decrypting the payload at the edge.

Summary for the Reader:

“Obfuscation is not a replacement for encryption, but a strategic amplifier. By removing the predictable signatures of our security protocols, we ensure that an attacker must first reverse-engineer the transport envelope before even attempting to challenge the underlying 256-bit AES or ChaCha20-Poly1305 safeguards.”

4. Cryptographic Rigidity Comparison

One of the most significant advantages of modern protocols is their lack of flexibility. Choice, in cryptography, is often the precursor to vulnerability.

5. The 32-Byte Standard: Entropy vs. Length

It is vital to distinguish between a “32-character string” and a “32-byte cryptographic key”.

• The Illusion of Security: Using string[:32] (slicing) limits the key to the human-readable ASCII range, significantly reducing the “Key Space”.
• The Gold Standard: Using os.urandom(32) ensures that every one of the 256 bits is truly random. This is the universal generation method for both PASETO and Branca, ensuring the token is mathematically unassailable by modern brute-force standards.

Final Engineering Takeaway

From the implementations and flows:

The most important difference is not encryption vs signing — it is when and how validation happens.

• JWT → validate late
• PASETO → validate during decrypt
• Branca → validate early + during decrypt

Practical Recommendation Matrix