tessl/maven-org-keycloak--keycloak-core

Core Keycloak library providing fundamental authentication and authorization functionality

—

Pending

Overview

Eval results

Files

Cryptographic Operations

Name: tessl/maven-org-keycloak--keycloak-core
Author: tessl

Comprehensive cryptographic support for signing, verification, key management, and algorithm abstraction with support for modern cryptographic standards including RSA, ECDSA, EdDSA, and HMAC.

Capabilities

Signature Contexts

Core interfaces for cryptographic signing and verification operations with pluggable algorithm support.

/**
 * Interface for cryptographic signature creation
 */
public interface SignatureSignerContext {
    /**
     * Create a signature for the provided data
     * @param data Data to sign
     * @return Signature bytes
     * @throws SignatureException if signing fails
     */
    byte[] sign(byte[] data) throws SignatureException;
    
    /**
     * Get the signing algorithm identifier
     * @return Algorithm name (e.g., "RS256", "ES256", "HS256")
     */
    String getAlgorithm();
    
    /**
     * Get the key identifier used for signing
     * @return Key ID or null if not available
     */
    String getKid();
}

/**
 * Interface for cryptographic signature verification
 */
public interface SignatureVerifierContext {
    /**
     * Verify a signature against the provided data
     * @param data Original data that was signed
     * @param signature Signature bytes to verify
     * @return true if signature is valid
     * @throws SignatureException if verification fails
     */
    boolean verify(byte[] data, byte[] signature) throws SignatureException;
    
    /**
     * Get the verification algorithm identifier
     * @return Algorithm name (e.g., "RS256", "ES256", "HS256")
     */
    String getAlgorithm();
    
    /**
     * Get the key identifier used for verification
     * @return Key ID or null if not available
     */
    String getKid();
}

Key Management

Comprehensive key wrapper and metadata management system for cryptographic keys.

/**
 * Container for cryptographic keys with associated metadata
 */
public class KeyWrapper {
    /**
     * Get the key identifier
     * @return Key ID string
     */
    public String getKid();
    
    /**
     * Get the cryptographic algorithm for this key
     * @return Algorithm identifier
     */
    public String getAlgorithm();
    
    /**
     * Get the key type
     * @return KeyType enum value
     */
    public KeyType getType();
    
    /**
     * Get the intended key usage
     * @return KeyUse enum value  
     */
    public KeyUse getUse();
    
    /**
     * Get the key status
     * @return KeyStatus enum value
     */
    public KeyStatus getStatus();
    
    /**
     * Get the public key (if available)
     * @return PublicKey instance or null
     */
    public PublicKey getPublicKey();
    
    /**
     * Get the secret key (if available)
     * @return SecretKey instance or null
     */
    public SecretKey getSecretKey();
    
    /**
     * Get the private key (if available)
     * @return PrivateKey instance or null
     */
    public PrivateKey getPrivateKey();
    
    /**
     * Get the X.509 certificate (if available)
     * @return Certificate instance or null
     */
    public Certificate getCertificate();
    
    /**
     * Get the certificate chain (if available)
     * @return Certificate array or null
     */
    public Certificate[] getCertificateChain();
}

/**
 * Container for multiple public keys with lookup capabilities
 */
public class PublicKeysWrapper {
    /**
     * Get all public keys
     * @return List of KeyWrapper instances
     */
    public List<KeyWrapper> getKeys();
    
    /**
     * Get a public key by key ID
     * @param kid Key identifier
     * @return KeyWrapper instance or null if not found
     */
    public KeyWrapper getKeyByKid(String kid);
    
    /**
     * Get keys by algorithm
     * @param algorithm Algorithm identifier
     * @return List of matching KeyWrapper instances
     */
    public List<KeyWrapper> getKeysByAlg(String algorithm);
}

Key Type and Status Enums

/**
 * Cryptographic key type constants interface
 */
public interface KeyType {
    /** Elliptic Curve keys */
    String EC = "EC";
    /** RSA keys */
    String RSA = "RSA";
    /** Octet sequence (symmetric) keys */
    String OCT = "OCT";
    /** Octet string key pairs (EdDSA) */
    String OKP = "OKP";
}

/**
 * Key usage enumeration
 */
public enum KeyUse {
    /** Signature and verification operations */
    SIG,
    /** Encryption and decryption operations */
    ENC
}

/**
 * Key status management enumeration
 */
public enum KeyStatus {
    /** Currently active key for signing and encryption */
    ACTIVE,
    /** Passive key for verification and decryption only */
    PASSIVE,
    /** Disabled key not used for any operations */
    DISABLED
}

Algorithm Constants

Comprehensive algorithm identifier constants for various cryptographic operations.

/**
 * Cryptographic algorithm constants interface
 */
public interface Algorithm {
    // RSA PKCS#1 v1.5 algorithms
    String RS256 = "RS256";
    String RS384 = "RS384";
    String RS512 = "RS512";
    
    // RSA PSS algorithms
    String PS256 = "PS256";
    String PS384 = "PS384";
    String PS512 = "PS512";
    
    // ECDSA algorithms
    String ES256 = "ES256";
    String ES384 = "ES384";
    String ES512 = "ES512";
    
    // EdDSA algorithms
    String EdDSA = "EdDSA";
    String Ed25519 = "Ed25519";
    String Ed448 = "Ed448";
    
    // HMAC algorithms
    String HS256 = "HS256";
    String HS384 = "HS384";
    String HS512 = "HS512";
    
    // AES Key Wrap algorithms
    String A128KW = "A128KW";
    String A192KW = "A192KW";
    String A256KW = "A256KW";
    
    // AES GCM Key Wrap algorithms
    String A128GCMKW = "A128GCMKW";
    String A192GCMKW = "A192GCMKW";
    String A256GCMKW = "A256GCMKW";
    
    // Direct encryption
    String DIR = "dir";
    
    // RSA OAEP algorithms
    String RSA1_5 = "RSA1_5";
    String RSA_OAEP = "RSA-OAEP";
    String RSA_OAEP_256 = "RSA-OAEP-256";
    
    // Content encryption algorithms
    String A128CBC_HS256 = "A128CBC-HS256";
    String A192CBC_HS384 = "A192CBC-HS384";
    String A256CBC_HS512 = "A256CBC-HS512";
    String A128GCM = "A128GCM";
    String A192GCM = "A192GCM";
    String A256GCM = "A256GCM";
}

Asymmetric Signature Implementations

RSA and ECDSA signature creation and verification implementations.

/**
 * Asymmetric signature creation context
 */
public class AsymmetricSignatureSignerContext implements SignatureSignerContext {
    /**
     * Create asymmetric signature signer
     * @param keyWrapper Key wrapper containing private key
     */
    public AsymmetricSignatureSignerContext(KeyWrapper keyWrapper);
    
    public byte[] sign(byte[] data) throws SignatureException;
    public String getAlgorithm();
    public String getKid();
}

/**
 * Asymmetric signature verification context
 */
public class AsymmetricSignatureVerifierContext implements SignatureVerifierContext {
    /**
     * Create asymmetric signature verifier
     * @param keyWrapper Key wrapper containing public key
     */
    public AsymmetricSignatureVerifierContext(KeyWrapper keyWrapper);
    
    public boolean verify(byte[] data, byte[] signature) throws SignatureException;
    public String getAlgorithm();
    public String getKid();
}

/**
 * ECDSA signature creation context
 */
public class ECDSASignatureSignerContext implements SignatureSignerContext {
    public ECDSASignatureSignerContext(KeyWrapper keyWrapper);
    public byte[] sign(byte[] data) throws SignatureException;
    public String getAlgorithm();
    public String getKid();
}

/**
 * ECDSA signature verification context
 */
public class ECDSASignatureVerifierContext implements SignatureVerifierContext {
    public ECDSASignatureVerifierContext(KeyWrapper keyWrapper);
    public boolean verify(byte[] data, byte[] signature) throws SignatureException;
    public String getAlgorithm();
    public String getKid();
}

HMAC Signature Implementations

HMAC-based signature creation and verification for shared secret scenarios.

/**
 * HMAC signature creation context
 */
public class MacSignatureSignerContext implements SignatureSignerContext {
    /**
     * Create HMAC signature signer
     * @param keyWrapper Key wrapper containing secret key
     */
    public MacSignatureSignerContext(KeyWrapper keyWrapper);
    
    public byte[] sign(byte[] data) throws SignatureException;
    public String getAlgorithm();
    public String getKid();
}

/**
 * HMAC signature verification context
 */
public class MacSignatureVerifierContext implements SignatureVerifierContext {
    /**
     * Create HMAC signature verifier
     * @param keyWrapper Key wrapper containing secret key
     */
    public MacSignatureVerifierContext(KeyWrapper keyWrapper);
    
    public boolean verify(byte[] data, byte[] signature) throws SignatureException;
    public String getAlgorithm();
    public String getKid();
}

ECDSA Algorithm Support

Elliptic Curve Digital Signature Algorithm utilities and curve definitions.

/**
 * ECDSA algorithm utilities
 */
public class ECDSAAlgorithm {
    /**
     * Get the Java algorithm name for an ECDSA algorithm identifier
     * @param algorithmId ECDSA algorithm ID (ES256, ES384, ES512)
     * @return Java algorithm name
     */
    public static String getJavaAlgorithm(String algorithmId);
    
    /**
     * Get the curve name for an ECDSA algorithm
     * @param algorithmId ECDSA algorithm ID
     * @return Curve name
     */
    public static String getCurve(String algorithmId);
}

/**
 * Elliptic curve definitions
 */
public enum ECCurve {
    P256("secp256r1", "ES256"),
    P384("secp384r1", "ES384"),
    P521("secp521r1", "ES512");
    
    private final String name;
    private final String algorithm;
    
    ECCurve(String name, String algorithm) {
        this.name = name;
        this.algorithm = algorithm;
    }
    
    public String getName();
    public String getAlgorithm();
}

Java Algorithm Mapping

Mapping between JOSE algorithm identifiers and Java cryptographic algorithm names.

/**
 * Java algorithm name mapping utilities
 */
public class JavaAlgorithm {
    /**
     * Get the Java algorithm name for a JOSE algorithm identifier
     * @param joseAlgorithm JOSE algorithm identifier
     * @return Java algorithm name
     */
    public static String getJavaAlgorithm(String joseAlgorithm);
    
    /**
     * Get the key algorithm for a signature algorithm
     * @param signatureAlgorithm Signature algorithm identifier
     * @return Key algorithm name
     */
    public static String getKeyAlgorithm(String signatureAlgorithm);
    
    /**
     * Check if algorithm is RSA-based
     * @param algorithm Algorithm identifier
     * @return true if RSA algorithm
     */
    public static boolean isRSA(String algorithm);
    
    /**
     * Check if algorithm is ECDSA-based
     * @param algorithm Algorithm identifier
     * @return true if ECDSA algorithm
     */
    public static boolean isECDSA(String algorithm);
    
    /**
     * Check if algorithm is HMAC-based
     * @param algorithm Algorithm identifier
     * @return true if HMAC algorithm
     */
    public static boolean isHMAC(String algorithm);
}

Exception Handling

/**
 * Exception thrown during cryptographic signature operations
 */
public class SignatureException extends Exception {
    public SignatureException(String message);
    public SignatureException(String message, Throwable cause);
}

/**
 * Exception thrown during hash operations
 */
public class HashException extends Exception {
    public HashException(String message);
    public HashException(String message, Throwable cause);
}

Usage Examples

import org.keycloak.crypto.*;
import java.security.KeyPair;
import java.security.KeyPairGenerator;

// RSA signature creation and verification
KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
keyGen.initialize(2048);
KeyPair keyPair = keyGen.generateKeyPair();

KeyWrapper signingKey = new KeyWrapper();
signingKey.setKid("rsa-key-1");
signingKey.setAlgorithm(Algorithm.RS256);
signingKey.setType(KeyType.RSA);
signingKey.setUse(KeyUse.SIG);
signingKey.setStatus(KeyStatus.ACTIVE);
signingKey.setPrivateKey(keyPair.getPrivate());
signingKey.setPublicKey(keyPair.getPublic());

// Create signature
SignatureSignerContext signer = new AsymmetricSignatureSignerContext(signingKey);
byte[] data = "Hello, World!".getBytes();
byte[] signature = signer.sign(data);

// Verify signature
KeyWrapper verifyingKey = new KeyWrapper();
verifyingKey.setKid("rsa-key-1");
verifyingKey.setAlgorithm(Algorithm.RS256);
verifyingKey.setPublicKey(keyPair.getPublic());

SignatureVerifierContext verifier = new AsymmetricSignatureVerifierContext(verifyingKey);
boolean isValid = verifier.verify(data, signature);

// HMAC signature with shared secret
KeyWrapper hmacKey = new KeyWrapper();
hmacKey.setKid("hmac-key-1");
hmacKey.setAlgorithm(Algorithm.HS256);
hmacKey.setType(KeyType.OCT);
hmacKey.setSecretKey(secretKey);

MacSignatureSignerContext hmacSigner = new MacSignatureSignerContext(hmacKey);
byte[] hmacSignature = hmacSigner.sign(data);

MacSignatureVerifierContext hmacVerifier = new MacSignatureVerifierContext(hmacKey);
boolean hmacValid = hmacVerifier.verify(data, hmacSignature);

Install with Tessl CLI

npx tessl i tessl/maven-org-keycloak--keycloak-core

docs

configuration-management.md

cryptographic-operations.md

identity-management.md

index.md

jose-implementation.md

security-context.md

token-management.md

token-representations.md

utility-functions.md

tile.json

tessl/maven-org-keycloak--keycloak-core