0
# Apache Ranger CredentialBuilder
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: credentialbuilder
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add Maven dependency:
10
  ```xml
11
  <dependency>
12
    <groupId>org.apache.ranger</groupId>
13
    <artifactId>credentialbuilder</artifactId>
14
    <version>2.7.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.apache.ranger.credentialapi.buildks;
22
import org.apache.ranger.credentialapi.CredentialReader;
23
```
24

25
## Basic Usage
26

27
```java
28
import org.apache.ranger.credentialapi.buildks;
29
import org.apache.ranger.credentialapi.CredentialReader;
30

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

34
// Create a new credential programmatically
35
String[] createArgs = {
36
    "create", 
37
    "myAlias", 
38
    "-value", 
39
    "mySecretPassword", 
40
    "-provider", 
41
    "jceks://file/path/to/keystore.jceks"
42
};
43
int result = credBuilder.createCredential(createArgs);
44

45
// Read a credential back
46
String decryptedPassword = CredentialReader.getDecryptedString(
47
    "/path/to/keystore.jceks", 
48
    "myAlias", 
49
    "jceks"
50
);
51

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

57
## Capabilities
58

59
### Credential Creation
60

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

63
```java { .api }
64
public class buildks {
65
    public buildks();
66
    
67
    public int createCredential(String[] args);
68
    public int createKeyStore(String[] args);
69
    public int createCredentialFromUserInput();
70
}
71
```
72

73
**createCredential** creates or updates encrypted credentials with automatic duplicate handling.
74

75
- **Parameters**: 
76
  - `args[0]`: "create" 
77
  - `args[1]`: alias name
78
  - `args[2]`: "-value"
79
  - `args[3]`: credential value
80
  - `args[4]`: "-provider" 
81
  - `args[5]`: provider path (e.g., "jceks://file/path/to/keystore.jceks")
82
  - `args[6]` (optional): "storeType"
83
  - `args[7]` (optional): store type value ("jceks", "bcfks")
84
- **Returns**: int (0 for success, -1 for failure)
85

86
**createKeyStore** performs lower-level keystore creation using Hadoop CredentialShell.
87

88
- **Parameters**: Same as createCredential
89
- **Returns**: int (0 for success, -1 for failure)
90

91
**createCredentialFromUserInput** provides interactive credential creation with user prompts.
92

93
- **Returns**: int (0 for success, -1 for failure)
94

95
Usage example:
96
```java
97
buildks builder = new buildks();
98

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

106
// Create credential with BCFKS keystore
107
String[] bcfksArgs = {
108
    "create", "apiKey", "-value", "key123", 
109
    "-provider", "bcfks://file/app/config/credentials.bcfks",
110
    "storeType", "bcfks"
111
};
112
int bcfksResult = builder.createCredential(bcfksArgs);
113
```
114

115
### Credential Retrieval
116

117
Retrieve and decrypt stored credentials from keystore files.
118

119
```java { .api }
120
public class CredentialReader {
121
    public static String getDecryptedString(String credentialProviderPath, String alias, String storeType);
122
}
123

124
public class buildks {
125
    public String getCredential(String[] args);
126
}
127
```
128

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

131
- **Parameters**:
132
  - `credentialProviderPath`: Path to keystore file or provider URL
133
  - `alias`: Credential alias name
134
  - `storeType`: Keystore type ("jceks", "bcfks", etc.)
135
- **Returns**: String (decrypted credential value or null if not found)
136

137
**getCredential** provides command-line style credential retrieval.
138

139
- **Parameters**: 
140
  - `args[0]`: "get"
141
  - `args[1]`: alias name
142
  - `args[2]`: "-provider"
143
  - `args[3]`: provider path
144
- **Returns**: String (decrypted credential value or null if not found/error)
145

146
Usage example:
147
```java
148
// Direct decryption
149
String password = CredentialReader.getDecryptedString(
150
    "/app/config/credentials.jceks", 
151
    "dbPassword", 
152
    "jceks"
153
);
154

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

161
### Credential Management
162

163
List and delete existing credentials in keystore files.
164

165
```java { .api }
166
public class buildks {
167
    public int listCredential(String[] args);
168
    public int deleteCredential(String[] args, boolean isSilentMode);
169
}
170
```
171

172
**listCredential** displays all available credential aliases in a keystore.
173

174
- **Parameters**:
175
  - `args[0]`: "list"
176
  - `args[1]`: "-provider"
177
  - `args[2]`: provider path
178
- **Returns**: int (0 for success, -1 for failure)
179

180
**deleteCredential** removes a credential from the keystore.
181

182
- **Parameters**:
183
  - `args[0]`: "delete"
184
  - `args[1]`: alias name
185
  - `args[2]`: "-provider"
186
  - `args[3]`: provider path
187
  - `isSilentMode`: boolean flag for non-interactive deletion
188
- **Returns**: int (0 for success, -1 for failure)
189

190
Usage example:
191
```java
192
buildks builder = new buildks();
193

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

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

203
### Command-Line Interface
204

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

207
```java { .api }
208
public class buildks {
209
    public static void main(String[] args);
210
    
211
    public static boolean isValidCreateCommand(String command, String alias, String valueOption, 
212
                                             String credential, String providerOption, String providerPath, 
213
                                             String storeTypeOption, String storeType);
214
    public static boolean isValidListCommand(String command, String providerOption, String providerPath, String storeType);
215
    public static boolean isValidGetCommand(String command, String alias, String providerOption, String providerPath, String storeType);
216
    
217
    public static void displayCommand(String[] args);
218
    public static void displaySyntax(String command, String storeType);
219
}
220
```
221

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

224
- **Parameters**: String array with command arguments
225
- Validates arguments and delegates to appropriate methods
226
- Exits with status 1 on error
227

228
**Validation methods** verify command syntax and parameters:
229
- **isValidCreateCommand**: Validates create command parameters
230
- **isValidListCommand**: Validates list command parameters  
231
- **isValidGetCommand**: Validates get command parameters
232
- **Returns**: boolean (true if valid, false otherwise)
233

234
**Utility methods**:
235
- **displayCommand**: Shows command being executed when debug mode enabled
236
- **displaySyntax**: Shows correct syntax for commands based on store type
237

238
Usage example:
239
```bash
240
# Command line usage
241
java -cp credentialbuilder-2.7.0.jar org.apache.ranger.credentialapi.buildks create myAlias -value myPassword -provider jceks://file/keystore.jceks
242

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

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

249
### Utility Functions
250

251
Helper methods for keystore management and validation.
252

253
```java { .api }
254
public class buildks {
255
    public void deleteInvalidKeystore(String providerPath);
256
}
257
```
258

259
**deleteInvalidKeystore** removes corrupted or empty keystore files.
260

261
- **Parameters**: `providerPath` - Path to keystore file or provider URL
262
- Automatically detects and removes files with zero length or invalid state
263

264
## Supported Keystore Formats
265

266
The library supports multiple Java KeyStore formats:
267

268
### JCEKS (Java Cryptography Extension KeyStore)
269
- **Default format** used when no store type specified
270
- **Provider URLs**: 
271
  - `jceks://file/path/to/keystore.jceks`
272
  - `jceks://file@/path/to/keystore.jceks` (alternative format)
273
  - `localjceks://file/path/to/keystore.jceks`
274
- **File extension**: `.jceks`
275

276
### BCFKS (Bouncy Castle FIPS KeyStore)
277
- **FIPS-compliant** keystore format
278
- **Provider URLs**: 
279
  - `bcfks://file/path/to/keystore.bcfks`
280
  - `bcfks://file@/path/to/keystore.bcfks` (alternative format)
281
  - `localbcfks://file/path/to/keystore.bcfks`
282
- **File extension**: `.bcfks`
283
- **Specify explicitly** with storeType parameter
284

285
## Error Handling
286

287
The library uses consistent error handling patterns:
288

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

295
Common error scenarios:
296
- Invalid provider URLs (must start with supported prefixes)
297
- Missing keystore files
298
- Incorrect alias names (case-sensitive)
299
- Corrupted keystore files (zero-length files are automatically cleaned up)
300
- Missing required parameters (command, alias, values, provider paths)
301
- Unsupported keystore types
302
- Invalid command syntax (use displaySyntax method for correct format)
303

304
## Dependencies
305

306
Key external dependencies used by the public API:
307

308
- `org.apache.hadoop.security.alias.CredentialShell` - Core credential operations
309
- `org.apache.hadoop.security.alias.CredentialProvider` - Provider interface
310
- `org.apache.hadoop.security.alias.CredentialProviderFactory` - Provider factory
311
- `org.apache.hadoop.security.alias.JavaKeyStoreProvider` - JCEKS provider
312
- `org.apache.hadoop.conf.Configuration` - Hadoop configuration framework
313
- `java.security.KeyStore` - Java KeyStore API
314

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