24.1 KeyStore Fundamentals and Operations

KeyStore is Java's secure storage mechanism for cryptographic keys and certificates. Understanding KeyStore fundamentals is essential for secure application development.

What is a KeyStore?

// KeyStore Overview
public class KeyStoreFundamentals {

    public static void printKeyStoreTypes() {
        System.out.println("=== KEYSTORE TYPES ===");
        System.out.println("\nJKS (Java KeyStore)");
        System.out.println("  - Legacy Java format");
        System.out.println("  - Proprietary to Java");
        System.out.println("  - Deprecated in favor of PKCS12");
        System.out.println("  - File extension: .jks");

        System.out.println("\nPKCS12 (Public-Key Cryptography Standards #12)");
        System.out.println("  - Industry standard format");
        System.out.println("  - Default since Java 9");
        System.out.println("  - Cross-platform compatible");
        System.out.println("  - File extension: .p12 or .pfx");
        System.out.println("  - RECOMMENDED");

        System.out.println("\nJCEKS (Java Cryptography Extension KeyStore)");
        System.out.println("  - Enhanced JKS format");
        System.out.println("  - Supports symmetric keys");
        System.out.println("  - File extension: .jceks");

        System.out.println("\nWindows-MY / Windows-ROOT");
        System.out.println("  - Windows certificate store integration");
        System.out.println("  - System keystore on Windows");

        System.out.println("\nPKCS11");
        System.out.println("  - Hardware security module (HSM) interface");
        System.out.println("  - Tokens, smart cards");
    }

    public static void printKeyStoreContents() {
        System.out.println("\n=== KEYSTORE CONTENTS ===");
        System.out.println("\nPrivate Key Entry");
        System.out.println("  - Private key (RSA, ECDSA, etc.)");
        System.out.println("  - Certificate chain (server cert + intermediates)");
        System.out.println("  - Protected by key password");
        System.out.println("  - Use: Server TLS, client certificates, signing");

        System.out.println("\nTrusted Certificate Entry");
        System.out.println("  - Public certificate only");
        System.out.println("  - No private key");
        System.out.println("  - Use: Trust anchors, CA certificates");

        System.out.println("\nSecret Key Entry (JCEKS only)");
        System.out.println("  - Symmetric encryption keys (AES, DES)");
        System.out.println("  - Use: Encryption, HMAC");
    }
}

Creating and Loading KeyStores

// KeyStore Creation and Loading
public class KeyStoreOperations {

    // Create new empty KeyStore
    public static KeyStore createEmptyKeyStore(String keyStoreType) throws Exception {
        KeyStore keyStore = KeyStore.getInstance(keyStoreType);
        keyStore.load(null, null); // Initialize empty
        return keyStore;
    }

    // Create PKCS12 KeyStore (recommended)
    public static KeyStore createPKCS12KeyStore() throws Exception {
        return createEmptyKeyStore("PKCS12");
    }

    // Load KeyStore from file
    public static KeyStore loadKeyStore(String keyStorePath, String password) 
            throws Exception {
        KeyStore keyStore = KeyStore.getInstance("PKCS12");

        try (InputStream is = new FileInputStream(keyStorePath)) {
            keyStore.load(is, password.toCharArray());
        }

        return keyStore;
    }

    // Load KeyStore with auto-detection of type
    public static KeyStore loadKeyStoreAutoDetect(String keyStorePath, String password) 
            throws Exception {
        // Try PKCS12 first
        try {
            KeyStore keyStore = KeyStore.getInstance("PKCS12");
            try (InputStream is = new FileInputStream(keyStorePath)) {
                keyStore.load(is, password.toCharArray());
            }
            return keyStore;
        } catch (Exception e) {
            // Fall back to JKS
            KeyStore keyStore = KeyStore.getInstance("JKS");
            try (InputStream is = new FileInputStream(keyStorePath)) {
                keyStore.load(is, password.toCharArray());
            }
            return keyStore;
        }
    }

    // Save KeyStore to file
    public static void saveKeyStore(KeyStore keyStore, String keyStorePath, 
                                   String password) throws Exception {
        try (OutputStream os = new FileOutputStream(keyStorePath)) {
            keyStore.store(os, password.toCharArray());
        }
    }

    // Complete example: Create, populate, save
    public static void demonstrateKeyStoreLifecycle() throws Exception {
        // 1. Create empty KeyStore
        KeyStore keyStore = createPKCS12KeyStore();
        System.out.println("Created empty PKCS12 KeyStore");

        // 2. Generate key pair and certificate (simplified)
        KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("RSA");
        keyPairGen.initialize(2048);
        KeyPair keyPair = keyPairGen.generateKeyPair();

        // 3. Add private key entry (certificate chain would be needed)
        // keyStore.setKeyEntry("mykey", keyPair.getPrivate(), 
        //                      "keypass".toCharArray(), certificateChain);

        // 4. Save KeyStore
        saveKeyStore(keyStore, "my-keystore.p12", "storepass");
        System.out.println("Saved KeyStore to my-keystore.p12");

        // 5. Load KeyStore
        KeyStore loadedKeyStore = loadKeyStore("my-keystore.p12", "storepass");
        System.out.println("Loaded KeyStore from file");
    }
}

KeyStore Entry Management

// Managing KeyStore Entries
public class KeyStoreEntryManagement {

    // List all aliases in KeyStore
    public static void listAliases(KeyStore keyStore) throws Exception {
        System.out.println("=== KEYSTORE ALIASES ===");
        Enumeration<String> aliases = keyStore.aliases();

        while (aliases.hasMoreElements()) {
            String alias = aliases.nextElement();
            System.out.println("\nAlias: " + alias);

            if (keyStore.isKeyEntry(alias)) {
                System.out.println("  Type: Private Key Entry");
                Certificate[] chain = keyStore.getCertificateChain(alias);
                System.out.println("  Chain length: " + 
                    (chain != null ? chain.length : 0));
            } else if (keyStore.isCertificateEntry(alias)) {
                System.out.println("  Type: Trusted Certificate Entry");
            }

            Certificate cert = keyStore.getCertificate(alias);
            if (cert instanceof java.security.cert.X509Certificate) {
                java.security.cert.X509Certificate x509 = 
                    (java.security.cert.X509Certificate) cert;
                System.out.println("  Subject: " + x509.getSubjectDN());
                System.out.println("  Issuer: " + x509.getIssuerDN());
                System.out.println("  Not After: " + x509.getNotAfter());
            }
        }
    }

    // Check if alias exists
    public static boolean aliasExists(KeyStore keyStore, String alias) 
            throws Exception {
        return keyStore.containsAlias(alias);
    }

    // Get private key
    public static PrivateKey getPrivateKey(KeyStore keyStore, String alias, 
                                          String keyPassword) throws Exception {
        if (!keyStore.isKeyEntry(alias)) {
            throw new KeyStoreException("Alias is not a key entry: " + alias);
        }

        Key key = keyStore.getKey(alias, keyPassword.toCharArray());
        if (!(key instanceof PrivateKey)) {
            throw new KeyStoreException("Key is not a private key: " + alias);
        }

        return (PrivateKey) key;
    }

    // Get certificate
    public static java.security.cert.X509Certificate getCertificate(
            KeyStore keyStore, String alias) throws Exception {
        Certificate cert = keyStore.getCertificate(alias);
        if (cert == null) {
            throw new KeyStoreException("Certificate not found: " + alias);
        }

        return (java.security.cert.X509Certificate) cert;
    }

    // Get certificate chain
    public static Certificate[] getCertificateChain(KeyStore keyStore, String alias) 
            throws Exception {
        if (!keyStore.isKeyEntry(alias)) {
            throw new KeyStoreException("Alias is not a key entry: " + alias);
        }

        Certificate[] chain = keyStore.getCertificateChain(alias);
        if (chain == null || chain.length == 0) {
            throw new KeyStoreException("No certificate chain for: " + alias);
        }

        return chain;
    }

    // Delete entry
    public static void deleteEntry(KeyStore keyStore, String alias) throws Exception {
        if (!keyStore.containsAlias(alias)) {
            throw new KeyStoreException("Alias not found: " + alias);
        }

        keyStore.deleteEntry(alias);
        System.out.println("Deleted entry: " + alias);
    }

    // Count entries
    public static void printKeyStoreStats(KeyStore keyStore) throws Exception {
        int keyEntries = 0;
        int certEntries = 0;

        Enumeration<String> aliases = keyStore.aliases();
        while (aliases.hasMoreElements()) {
            String alias = aliases.nextElement();
            if (keyStore.isKeyEntry(alias)) {
                keyEntries++;
            } else if (keyStore.isCertificateEntry(alias)) {
                certEntries++;
            }
        }

        System.out.println("=== KEYSTORE STATISTICS ===");
        System.out.println("Total entries: " + keyStore.size());
        System.out.println("Private key entries: " + keyEntries);
        System.out.println("Trusted certificate entries: " + certEntries);
    }
}

Adding Private Key Entries

// Adding Private Keys to KeyStore
public class PrivateKeyEntryManagement {

    // Add private key with certificate chain
    public static void addPrivateKeyEntry(KeyStore keyStore, String alias,
                                         PrivateKey privateKey, String keyPassword,
                                         Certificate[] certificateChain) 
            throws Exception {
        keyStore.setKeyEntry(alias, privateKey, keyPassword.toCharArray(), 
                           certificateChain);
        System.out.println("Added private key entry: " + alias);
    }

    // Add private key from PEM files
    public static void addPrivateKeyFromPEM(KeyStore keyStore, String alias,
                                           String privateKeyPath,
                                           String certificatePath,
                                           String keyPassword) throws Exception {
        // Read private key (would need PEM parsing library like BouncyCastle)
        // This is simplified - actual implementation needs proper PEM parsing

        System.out.println("Reading private key from: " + privateKeyPath);
        System.out.println("Reading certificate from: " + certificatePath);

        // In practice, use:
        // - java.security.KeyFactory for key parsing
        // - java.security.cert.CertificateFactory for certificate parsing
        // - Or BouncyCastle PEMParser for easier PEM handling
    }

    // Update private key entry (replace certificate chain)
    public static void updateCertificateChain(KeyStore keyStore, String alias,
                                             String keyPassword,
                                             Certificate[] newChain) 
            throws Exception {
        // Get existing private key
        PrivateKey privateKey = (PrivateKey) keyStore.getKey(
            alias, keyPassword.toCharArray());

        if (privateKey == null) {
            throw new KeyStoreException("Private key not found: " + alias);
        }

        // Replace with new chain
        keyStore.setKeyEntry(alias, privateKey, keyPassword.toCharArray(), newChain);
        System.out.println("Updated certificate chain for: " + alias);
    }

    // Convert key entry to different alias
    public static void copyKeyEntry(KeyStore sourceKS, String sourceAlias,
                                   KeyStore destKS, String destAlias,
                                   String keyPassword) throws Exception {
        // Get private key
        PrivateKey privateKey = (PrivateKey) sourceKS.getKey(
            sourceAlias, keyPassword.toCharArray());

        // Get certificate chain
        Certificate[] chain = sourceKS.getCertificateChain(sourceAlias);

        // Add to destination
        destKS.setKeyEntry(destAlias, privateKey, keyPassword.toCharArray(), chain);
        System.out.println("Copied key entry from " + sourceAlias + " to " + destAlias);
    }
}

Adding Trusted Certificate Entries

// Managing Trusted Certificates
public class TrustedCertificateManagement {

    // Add trusted certificate
    public static void addTrustedCertificate(KeyStore keyStore, String alias,
                                            Certificate certificate) 
            throws Exception {
        keyStore.setCertificateEntry(alias, certificate);
        System.out.println("Added trusted certificate: " + alias);
    }

    // Load certificate from file
    public static java.security.cert.X509Certificate loadCertificateFromFile(
            String certificatePath) throws Exception {
        CertificateFactory cf = CertificateFactory.getInstance("X.509");

        try (InputStream is = new FileInputStream(certificatePath)) {
            Certificate cert = cf.generateCertificate(is);
            return (java.security.cert.X509Certificate) cert;
        }
    }

    // Add CA certificate from file
    public static void addCAFromFile(KeyStore keyStore, String alias,
                                    String caCertPath) throws Exception {
        java.security.cert.X509Certificate caCert = 
            loadCertificateFromFile(caCertPath);

        addTrustedCertificate(keyStore, alias, caCert);
        System.out.println("Added CA certificate from: " + caCertPath);
    }

    // Import system trust store certificates
    public static void importSystemTrustStore(KeyStore targetKeyStore) 
            throws Exception {
        // Load default system trust store
        TrustManagerFactory tmf = TrustManagerFactory.getInstance(
            TrustManagerFactory.getDefaultAlgorithm());
        tmf.init((KeyStore) null); // null = use default

        // Get trusted certificates
        for (TrustManager tm : tmf.getTrustManagers()) {
            if (tm instanceof javax.net.ssl.X509TrustManager) {
                javax.net.ssl.X509TrustManager x509tm = 
                    (javax.net.ssl.X509TrustManager) tm;

                java.security.cert.X509Certificate[] acceptedIssuers = 
                    x509tm.getAcceptedIssuers();

                System.out.println("Importing " + acceptedIssuers.length + 
                                 " system certificates");

                for (java.security.cert.X509Certificate cert : acceptedIssuers) {
                    String alias = cert.getSubjectDN().toString();
                    targetKeyStore.setCertificateEntry(alias, cert);
                }
            }
        }
    }

    // Check if certificate is trusted
    public static boolean isCertificateTrusted(KeyStore keyStore,
                                              java.security.cert.X509Certificate cert) 
            throws Exception {
        String alias = keyStore.getCertificateAlias(cert);
        return alias != null;
    }
}

KeyStore Security Best Practices

// KeyStore Security
public class KeyStoreSecurity {

    public static void printSecurityBestPractices() {
        System.out.println("=== KEYSTORE SECURITY BEST PRACTICES ===");

        System.out.println("\n1. PASSWORD PROTECTION");
        System.out.println("   - Use strong passwords (16+ characters)");
        System.out.println("   - Different passwords for keystore and keys");
        System.out.println("   - Never hardcode passwords in source");
        System.out.println("   - Load from environment variables or vault");

        System.out.println("\n2. FILE PERMISSIONS");
        System.out.println("   - Unix: chmod 600 (owner read/write only)");
        System.out.println("   - Windows: Restrict to owner using ACLs");
        System.out.println("   - Never commit keystores to version control");

        System.out.println("\n3. KEYSTORE FORMAT");
        System.out.println("   - Use PKCS12 (industry standard)");
        System.out.println("   - Avoid legacy JKS format");
        System.out.println("   - Consider HSM for production");

        System.out.println("\n4. KEY SEPARATION");
        System.out.println("   - Separate keystores by purpose:");
        System.out.println("     * Server TLS keys");
        System.out.println("     * Client certificates");
        System.out.println("     * Code signing keys");
        System.out.println("     * Trusted CA certificates");

        System.out.println("\n5. ROTATION AND EXPIRATION");
        System.out.println("   - Monitor certificate expiration");
        System.out.println("   - Automate certificate renewal");
        System.out.println("   - Rotate keys periodically");
        System.out.println("   - Test rotation procedures");

        System.out.println("\n6. BACKUP AND RECOVERY");
        System.out.println("   - Encrypted backups only");
        System.out.println("   - Separate backup location");
        System.out.println("   - Document recovery procedures");
        System.out.println("   - Test recovery process");
    }

    // Load password from environment
    public static String loadPasswordFromEnvironment(String envVarName) {
        String password = System.getenv(envVarName);
        if (password == null || password.isEmpty()) {
            throw new SecurityException(
                "Password not found in environment: " + envVarName);
        }
        return password;
    }

    // Validate keystore file permissions (Unix)
    public static void validateFilePermissions(String keyStorePath) throws Exception {
        Path path = Paths.get(keyStorePath);

        // Check file exists
        if (!Files.exists(path)) {
            throw new FileNotFoundException("KeyStore not found: " + keyStorePath);
        }

        // Check permissions (Unix)
        java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions = 
            Files.getPosixFilePermissions(path);

        boolean ownerReadable = permissions.contains(
            java.nio.file.attribute.PosixFilePermission.OWNER_READ);
        boolean ownerWritable = permissions.contains(
            java.nio.file.attribute.PosixFilePermission.OWNER_WRITE);
        boolean groupReadable = permissions.contains(
            java.nio.file.attribute.PosixFilePermission.GROUP_READ);
        boolean othersReadable = permissions.contains(
            java.nio.file.attribute.PosixFilePermission.OTHERS_READ);

        if (groupReadable || othersReadable) {
            System.err.println("WARNING: KeyStore readable by group or others!");
            System.err.println("Run: chmod 600 " + keyStorePath);
        }

        if (ownerReadable && ownerWritable && !groupReadable && !othersReadable) {
            System.out.println("✓ KeyStore permissions are secure");
        }
    }
}

Best Practices

• Use PKCS12 format: Default and industry standard since Java 9.
• Strong passwords: 16+ characters for keystore and key passwords.
• Secure file permissions: chmod 600 on Unix, restrict ACLs on Windows.
• Never hardcode passwords: Load from environment or secure vault.
• Separate keystores by purpose: TLS server, client certs, trust anchors.
• Monitor expiration: Set alerts for certificate expiration.
• Regular backups: Encrypted backups in separate location.
• Key rotation: Plan and test certificate renewal procedures.
• Use aliases wisely: Descriptive names for easy identification.
• Audit access: Log keystore access and modifications.