Apache Ranger CredentialBuilder

Secure credential management library for Java applications outside the Hadoop ecosystem. Provides encrypted credential storage using Java KeyStore formats (JCEKS and BCFKS) with command-line and programmatic APIs for creating, retrieving, listing, and deleting encrypted credentials.

Package Information

• Package Name: credentialbuilder
• Package Type: maven
• Language: Java
• Installation: Add Maven dependency:

  <dependency>
    <groupId>org.apache.ranger</groupId>
    <artifactId>credentialbuilder</artifactId>
    <version>2.7.0</version>
  </dependency>

Core Imports

import org.apache.ranger.credentialapi.buildks;
import org.apache.ranger.credentialapi.CredentialReader;

Basic Usage

import org.apache.ranger.credentialapi.buildks;
import org.apache.ranger.credentialapi.CredentialReader;

// Create a credential builder instance
buildks credBuilder = new buildks();

// Create a new credential programmatically
String[] createArgs = {
    "create", 
    "myAlias", 
    "-value", 
    "mySecretPassword", 
    "-provider", 
    "jceks://file/path/to/keystore.jceks"
};
int result = credBuilder.createCredential(createArgs);

// Read a credential back
String decryptedPassword = CredentialReader.getDecryptedString(
    "/path/to/keystore.jceks", 
    "myAlias", 
    "jceks"
);

// List all credentials in keystore
String[] listArgs = {"list", "-provider", "jceks://file/path/to/keystore.jceks"};
credBuilder.listCredential(listArgs);

Capabilities

Credential Creation

Create encrypted credentials in keystore files with support for different store types.

public class buildks {
    public buildks();
    
    public int createCredential(String[] args);
    public int createKeyStore(String[] args);
    public int createCredentialFromUserInput();
}

createCredential creates or updates encrypted credentials with automatic duplicate handling.

• Parameters:
  • args[0]: "create"
  • args[1]: alias name
  • args[2]: "-value"
  • args[3]: credential value
  • args[4]: "-provider"
  • args[5]: provider path (e.g., "jceks://file/path/to/keystore.jceks")
  • args[6] (optional): "storeType"
  • args[7] (optional): store type value ("jceks", "bcfks")
• Returns: int (0 for success, -1 for failure)

createKeyStore performs lower-level keystore creation using Hadoop CredentialShell.

• Parameters: Same as createCredential
• Returns: int (0 for success, -1 for failure)

createCredentialFromUserInput provides interactive credential creation with user prompts.

• Returns: int (0 for success, -1 for failure)

Usage example:

buildks builder = new buildks();

// Create credential with JCEKS keystore
String[] args = {
    "create", "dbPassword", "-value", "secretPass123", 
    "-provider", "jceks://file/app/config/credentials.jceks"
};
int result = builder.createCredential(args);

// Create credential with BCFKS keystore
String[] bcfksArgs = {
    "create", "apiKey", "-value", "key123", 
    "-provider", "bcfks://file/app/config/credentials.bcfks",
    "storeType", "bcfks"
};
int bcfksResult = builder.createCredential(bcfksArgs);

Credential Retrieval

Retrieve and decrypt stored credentials from keystore files.

public class CredentialReader {
    public static String getDecryptedString(String credentialProviderPath, String alias, String storeType);
}

public class buildks {
    public String getCredential(String[] args);
}

getDecryptedString is the main API method for retrieving and decrypting stored credentials.

• Parameters:
  • credentialProviderPath: Path to keystore file or provider URL
  • alias: Credential alias name
  • storeType: Keystore type ("jceks", "bcfks", etc.)
• Returns: String (decrypted credential value or null if not found)

getCredential provides command-line style credential retrieval.

• Parameters:
  • args[0]: "get"
  • args[1]: alias name
  • args[2]: "-provider"
  • args[3]: provider path
• Returns: String (decrypted credential value or null if not found/error)

Usage example:

// Direct decryption
String password = CredentialReader.getDecryptedString(
    "/app/config/credentials.jceks", 
    "dbPassword", 
    "jceks"
);

// Command-style retrieval
buildks builder = new buildks();
String[] getArgs = {"get", "dbPassword", "-provider", "jceks://file/app/config/credentials.jceks"};
String password2 = builder.getCredential(getArgs);

Credential Management

List and delete existing credentials in keystore files.

public class buildks {
    public int listCredential(String[] args);
    public int deleteCredential(String[] args, boolean isSilentMode);
}

listCredential displays all available credential aliases in a keystore.

• Parameters:
  • args[0]: "list"
  • args[1]: "-provider"
  • args[2]: provider path
• Returns: int (0 for success, -1 for failure)

deleteCredential removes a credential from the keystore.

• Parameters:
  • args[0]: "delete"
  • args[1]: alias name
  • args[2]: "-provider"
  • args[3]: provider path
  • isSilentMode: boolean flag for non-interactive deletion
• Returns: int (0 for success, -1 for failure)

Usage example:

buildks builder = new buildks();

// List all credentials
String[] listArgs = {"list", "-provider", "jceks://file/app/config/credentials.jceks"};
builder.listCredential(listArgs);

// Delete a credential
String[] deleteArgs = {"delete", "oldPassword", "-provider", "jceks://file/app/config/credentials.jceks"};
builder.deleteCredential(deleteArgs, true); // Silent mode

Command-Line Interface

Main entry point for command-line usage with validation utilities.

public class buildks {
    public static void main(String[] args);
    
    public static boolean isValidCreateCommand(String command, String alias, String valueOption, 
                                             String credential, String providerOption, String providerPath, 
                                             String storeTypeOption, String storeType);
    public static boolean isValidListCommand(String command, String providerOption, String providerPath, String storeType);
    public static boolean isValidGetCommand(String command, String alias, String providerOption, String providerPath, String storeType);
    
    public static void displayCommand(String[] args);
    public static void displaySyntax(String command, String storeType);
}

main provides command-line entry point supporting "create" and "list" commands.

• Parameters: String array with command arguments
• Validates arguments and delegates to appropriate methods
• Exits with status 1 on error

Validation methods verify command syntax and parameters:

• isValidCreateCommand: Validates create command parameters
• isValidListCommand: Validates list command parameters
• isValidGetCommand: Validates get command parameters
• Returns: boolean (true if valid, false otherwise)

Utility methods:

• displayCommand: Shows command being executed when debug mode enabled
• displaySyntax: Shows correct syntax for commands based on store type

Usage example:

# Command line usage
java -cp credentialbuilder-2.7.0.jar org.apache.ranger.credentialapi.buildks create myAlias -value myPassword -provider jceks://file/keystore.jceks

# Alternative format (as used in tests)
java -cp credentialbuilder-2.7.0.jar org.apache.ranger.credentialapi.buildks create myAlias -value myPassword -provider jceks://file@/keystore.jceks

java -cp credentialbuilder-2.7.0.jar org.apache.ranger.credentialapi.buildks list -provider jceks://file/keystore.jceks

Utility Functions

Helper methods for keystore management and validation.

public class buildks {
    public void deleteInvalidKeystore(String providerPath);
}

deleteInvalidKeystore removes corrupted or empty keystore files.

• Parameters: providerPath - Path to keystore file or provider URL
• Automatically detects and removes files with zero length or invalid state

Supported Keystore Formats

The library supports multiple Java KeyStore formats:

JCEKS (Java Cryptography Extension KeyStore)

• Default format used when no store type specified
• Provider URLs:
  • jceks://file/path/to/keystore.jceks
  • jceks://file@/path/to/keystore.jceks (alternative format)
  • localjceks://file/path/to/keystore.jceks
• File extension: .jceks

BCFKS (Bouncy Castle FIPS KeyStore)

• FIPS-compliant keystore format
• Provider URLs:
  • bcfks://file/path/to/keystore.bcfks
  • bcfks://file@/path/to/keystore.bcfks (alternative format)
  • localbcfks://file/path/to/keystore.bcfks
• File extension: .bcfks
• Specify explicitly with storeType parameter

Error Handling

The library uses consistent error handling patterns:

• Return codes: Methods return 0 for success, -1 for failure
• Null returns: getDecryptedString() returns null for missing/invalid credentials
• Exception handling: Internal exceptions are caught and logged to stderr
• Validation: All input parameters are validated before processing
• Automatic cleanup: Invalid or corrupted keystores are automatically detected and removed

Common error scenarios:

• Invalid provider URLs (must start with supported prefixes)
• Missing keystore files
• Incorrect alias names (case-sensitive)
• Corrupted keystore files (zero-length files are automatically cleaned up)
• Missing required parameters (command, alias, values, provider paths)
• Unsupported keystore types
• Invalid command syntax (use displaySyntax method for correct format)

Dependencies

Key external dependencies used by the public API:

• org.apache.hadoop.security.alias.CredentialShell - Core credential operations
• org.apache.hadoop.security.alias.CredentialProvider - Provider interface
• org.apache.hadoop.security.alias.CredentialProviderFactory - Provider factory
• org.apache.hadoop.security.alias.JavaKeyStoreProvider - JCEKS provider
• org.apache.hadoop.conf.Configuration - Hadoop configuration framework
• java.security.KeyStore - Java KeyStore API

These dependencies are automatically resolved through Maven when including the credentialbuilder artifact.