Introduction
- The "Password Safe" (Credential Store, CS) connection and other data to be encrypted and stored securely and independently of the application(s) such as.YADE that use this data. Access to the CS is only possible with access methods such as an SSH key or password.
- Currently CS is using "KeePass" and "KeePassX" with the db version 1.0, thus CS can be used on most popular OS platforms.
- The advantage of using CS is that CS stores the credentials (and other information/parameters) into a standardized, secure and encrypted database, i.e. Keepass. YADE will access the CS database using a standard interface. The CS database can only be accessed using password, encryption-key file (ppk) or a combination of both. The CS password is used to encrypt the contents stored in the CS database with AES.
- CS can be used to securely store information or parameters, database connection URL, run-time decryption key and other access data.
The following information can be retrieved from CS standard fields:
- UserID : The user identification of a user who is authorized for the operation.
- Password : Assigned password for the user.
- Server-Name : Target server name or IP address
- Notes : In the notes section of the CS other parameters/options can be stored, i.e. YADE parameters, database connection URL etc. The extra options are defined in a similarly way as used on the command line.
- File-Attachment : Files such as PGP or SSH private key files can be stored in the CS as attachments. Applications will retrieve the attached file at run-time and will delete the file immediately once operation is completed.
Scope
This article describes the use of the Credential Store with the YADE Client via the client's command line interface.
A description of the use of the Credential Store with the YADE JITL job can be found in the Jobs JADEJob & JADE4DMZJob article.
Configuration Procedure
The examples presented in this article are based on the simple file transfer example described in the The YADE Client Command Line Interface - Tutorial 1 - Getting Started article. This tutorial describes the configuration required to download a number of files from a online server provided by the SOS GmbH and save these file on the user's local file system. Using this server means that users can get a working example up and running with a minimum of effort. A simplified version of the configuration used in the tutorial (only specifying FTP) is available as a download: sos-berlin_demo_2_local.xml. Instructions for installing and configuring the YADE Client can be found in the YADE - Tutorials article.
The configuration provided in the download file will cause six files in the root server folder to be copied to a local /jade_demo/transfer_receive folder, generating the target folder in the user's home or profile directory if required and permissions are available. The files will be transferred by FTP and authentication for the server (user name and password) is specified in the download file.
Installing and configuring the Credential Store
The installation of KeePass II is described on the Keepass Web Site.
For the examples described in the current article the following database was configured (on a Windows system):
- Path & name:
%USERPROFILE%\jade_demo\keepass\demo_cred_store.kdbx - Master Password:
sos
The following information was specified in the database:
- Database:
demo_database - Group:
demo - Title:
demo on test.sos-berlin.com - UserId:
demo - Password:
demo - URL:
test.sos-berlin.com(alternatively, the IP address could have been specified here.
Integrating the Credential Store in a File Transfer Configuration
The use of the Credential Store is specified in YADE Client file transfer configuration files, which are written in XML. We recommend using the SOS XML Editor to edit these files. Instructions for downloading, installing and using the XML Editor are linked from this page.
In the remainder of the current article, it is assumed that readers have made themselves familiar with the organization of the YADE Client file transfer configurations into Profiles and Fragments. This is described in the Getting Started YADE tutorial linked above.
The following configuration elements are required to specify the use of a Credential Store:
- A Credential Store Fragments element that at the same level in the XML hierarchy as the Protocol Fragments elements.
- A Credential Store Fragment element that is referenced from the Protocol Fragment. This Fragment specifies the location and authentication for the Credential Store.
- The values of the connection and authentication elements are modified to refer to elements stored within the Credential Store.
The XML Configuration
The parts of the XML configuration relevant to the use of the Credential Store are shown in the following screenshot of the XML Editor:
Running the YADE Client with the Credential Store
The use of the Credential Store is contained within the settings file and is not exposed when calling the client. For example, for Windows systems:
C:\Program Files\sos-berlin.com\jade\client\bin>jade.cmd -settings="%USERPROFILE%\jade_demo\sos-berlin_demo_2_local.xml" -profile="ftp_server_2_local_cs"
The output produced when successful:
See Also:
Parameter used by SOS Credential Store
Name | Title | Mandatory | Default |
|---|---|---|---|
Process additional parameters from "notes" filed | false | false | |
CredentialStore_OverwriteExportedFile | false | true | |
CredentialStore_Permissions4ExportedFile | false | 600 | |
Delete Attachment On Exit of Application | false | true | |
Export attached file to disc | false | false | |
Name of the extracted attachment file | false |
| |
Name of the File containing the private Key | false |
| |
Password for CS | false |
| |
Authentication Method for the CS | true | privatekey | |
The Type of the crendential store application | false | KeePass | |
Path and Key for the credentials | true |
| |
Name of Credential Database | true |
| |
use credential store for authentication | false | false |
Parameter CredentialStore_ProcessNotesParams: Process additional parameters from notes field
- In the notes field of the CS database extra parameters like a database connection string , Proxy server IP etc. can be defined. These parameters will be processed with other parameters defined in settings file, JITL parameters. If a parameter with the same name is defined in the notes section then the parameter value in the notes of the CS will have priority.
-dburl=test -verbose=2 -password=12345
- The notes properties of KeePass can be used to store extra parameters, i.e. options such as a database connection string, proxy server settings etc.
- Data-Type : SOSOptionBoolean
- The default value for this parameter is:
false. - Use together with parameter:
- use_credential_Store - use credential store for authentication
- Alias: CS_ProcessNotesParams
Parameter CredentialStore_OverwriteExportedFile
- At run-time YADE can export the file stored in the attachment field of the CS database to the local file system. For example If the attached file is an SSH key and YADE had to use the key file for file transfer operations. YADE will export the attached file into a predefined directory i.e. $HOME/.ssh. To avoid any unwanted overwriting of existing files in the $HOME/.ssh folder set this parameter as false.
- Data-Type: SOSOptionBoolean
- The default value for this parameter is:
true. - Use together with parameter:
- use_credential_Store - use credential store for authentication
- Alias: CS_OverwriteExportedFile
Parameter CredentialStore_Permissions4ExportedFile
- At run-time YADE can export the file defined in the attachment filed of the CS database to the local file system. For example If the attached file is an SSH key and YADE wants to use the key file for file transfer operations then YADE will export the attached file to a predefined directory, i.e. $HOME/.ssh, and the key file should have specific permissions.
-CredentialStore_Permissions4ExportedFile="600"
- Data-Type: SOSOptionString
- The default value for this parameter is:
600. - Use together with parameter:
- use_credential_Store - use credential store for authentication
- CredentialStore_ExportAttachment - Export attached file to disc
- Alias: CS_Permissions4ExportedFile
Parameter CredentialStore_DeleteExportedFileOnExit: Delete Attachment On Exit of Application
- At run-time YADE will export the attached file of a CS to the local file system and once its operation is completed and irrespective of operation's status by default YADE will delete this file. In special cases, e.g. for debuging, if you want YADE not to delete the file then set this parameter as
false. - Data-Type : SOSOptionBoolean
- The default value for this parameter is
true. - Use together with parameter:
- use_credential_Store - use credential store for authentication
- Alias: CS_DeleteExportedFileOnExit
Parameter CredentialStore_ExportAttachment: Export attached file to disc
- YADE can export a file that is stored in the CS database as attachment to the local file system. By default YADE does not export attached files.
- Data-Type: SOSOptionBoolean
- The default value for this parameter is:
false. - Alias: CS_ExportAttachment
Parameter CredentialStore_ExportAttachment2FileName: Name of the extracted attachment file
To use the file stored in the CS as attachment during an operation, YADE has to export the attached file to the local file system. Use this parameter to define the name of exported file in the local file system.
-CredentialStore_ExportAttachment2FileName="archive_server_ras.ppk"
- Data-Type: SOSOptionOutFileName
- Use together with parameter:
- use_credential_Store - use credential store for authentication
- Alias: CS_ExportAttachment2FileName
Parameter CredentialStore_KeyFileName: Name of the File containing the private Key
Credential Store can be accessed by YADE using a private key or using a password or a combination of both. Define the path/location of the SSH key file using this parameter.
-CredentialStore_KeyFileName="jade_cs_rsa.ppk"
- Data-Type: SOSOptionInFileName
- Use together with parameter:
- use_credential_Store - use credential store for authentication
- Alias: CS_KeyFileName
Parameter CredentialStore_password: Password for CS
The Credential Store can be accessed by YADE using a private key or using a password or a combination of both. Define the CS access password using this parameter. Hint: always use a strong password for CS.
-CredentialStore_password="55ybr293N!2BButnY4,w"
Data-Type: SOSOptionPassword
Use together with parameter:
- use_credential_Store - use credential store for authentication
Alias: CS_password
Parameter CredentialStore_AuthenticationMethod: Authentication Method for the CS
There are three possible combinations of authentication methods.
-CredentialStoreAuthenticationMethod="password"
--- OR ---
-CredentialStoreAuthenticationMethod="privatekey"
--- OR ---
-CredentialStoreAuthenticationMethod="password+privatekey"
- Data-Type: SOSOptionString
- The default value for this parameter is:
privatekey. - Use together with parameter:
- use_credential_Store - use credential store for authentication
- This parameter is mandatory.
- Alias: CS_AuthenticationMethod
Parameter CredentialStore_StoreType: The Type of the crendential store application
- At present only "KeePass" as CS database is supported and only
KeePassas valid parameter value is permitted. - Data-Type: SOSOptionString
- The default value for this parameter is:
KeePass. - Use together with parameter:
- use_credential_Store - use credential store for authentication
- Alias: CS_StoreType
Parameter CredentialStore_KeyPath: Path and Key for the credentials
- This option specifies the path of the access key for access to the credential store..
- Credential store can be accessed by the YADE using a private key or using a password or a combination of both. Define the path/location of the SSH key file using this parameter.
-CredentialStore_KeyFileName="/ssh/server1/sap-upload"
- Data-Type: SOSOptionString
- Use together with parameter:
- use_credential_Store - use credential store for authentication
- This parameter is mandatory.
- Alias: CS_KeyPath
Parameter CredentialStore_FileName: Name of Credential Database
- The path and name of the KeePass or KeePassX database file with the file extension .kdb.
Command-Line : jade.sh -CredentialStoreFileName="/etc/keystore/sap_jade.kdb"
YADE profile : CredentialStoreFileName = /etc/keystore/sap_jade.kdb
Java API : CSOptions.CredentialStoreFileName.Value("/etc/keystore/sap_jade.kdb");
- Data-Type : SOSOptionInFileName
- Use together with parameter:
- use_credential_Store - use credential store for authentication
- This parameter is mandatory.
- Alias: CS_FileName
Parameter use_credential_Store: use credential store for authentication
- If you want to store your access data, i.e. user id, password, SSH key, database connection string in an encrypted CS database, then enable this parameter and configure access to the CS accordingly. By default YADE will look for the parameters from its configuration file, from the command line or from the JITL Job.
- Data-Type: SOSOptionBoolean
- The default value for this parameter is:
false.
Example of YADE Profile using Credential Store : jade_settings.ini
[Keepass_DataBase_WithPassword]
use_credential_Store = true
CredentialStore_FileName = R:\backup\sos\java\development\com.sos.VirtualFileSystem\keepassX-test.kdb
CredentialStore_KeyPath = sos/server/homer.sos
CredentialStore_password = testing
[ReceiveUsingKeePass]
include = Keepass_DataBase_WithPassword
source_CredentialStore_KeyPath = sos/server/homer.sos
source_include = Keepass_DataBase_WithPassword
source_Dir = /tmp/test/jade/out
source_make_Dirs = true
source_loadClassName = com.sos.VirtualFileSystem.FTP.SOSVfsFtp2
target_protocol = local
target_dir = /tmp/test/jade/in
operation = copy
file_spec = \.txt$
transfer_mode = ascii
source_transfer_mode = ascii
loadClassName = com.sos.VirtualFileSystem.FTP.SOSVfsFtp2