Examples, syntax, and exceptions - Java

This topic describes syntax and examples of Java Application Password SDK.

The Java Application Password SDK comprises several classes, which contain methods that enable you to specify the password to retrieve and the configurations that enable the Credential Provider to retrieve them.

Examples

The following examples show how to retrieve a password from the Vault with the Java Application Password SDK.

Syntax - Class: PSDKPasswordRequest

This class manages requests for password objects. It specifies details about the password and its location in the Vault, as well as the location of the credential file that the application uses to authenticate to the Credential Provider.

This class has the following constructor:

This class has the following methods:

These methods are described below.

Constructor

PSDKPasswordRequest ()

Description

Constructs an object for the password request.

Syntax

 

PSDKPasswordRequest ()

Throws

PSDKException

Methods

setSafe

Description

This method specifies the name of the Safe where the password is stored.

Mandatory

Yes

Default

No

Syntax

 

public void setSafe (String safeName)

 

The following table displays the parameters of the setSafe method:

Parameter

safeName

Description

A string that represents the name of the Safe where the password is stored.

Throws

PSDKException

setFolder

Description

This method specifies the name of the folder where the password is stored.

Mandatory

No

Default

‘root’

 

The ‘root’ folder is the default value if the Safe and object are specified, but not the folder. If the Safe and object are not specified, the Credential Provider will search in all the folders starting from the ‘root’ folder.

Syntax

 

public void setFolder (String folderName)

 

The following table displays the parameters of the setFolder method:

Parameter

folderName

Description

A string that represents the name of the folder where the password is stored.

Throws

PSDKException

setObject

Description

This method specifies the name of the password object to retrieve.

Mandatory

Yes

Default

No

Syntax

 

public void setObject (String objectName)

 

The following table displays the parameters of the setObject method:

Parameter

objectName

Description

A string that represents the name of the password to retrieve.

Throws

PSDKException

setAppID

Description

This method specifies the unique ID of the application issuing the password request.

Note: This parameter is required.

Mandatory

Yes

Default

No

Syntax

 

public void setAppID (String appId)

 

The following table displays the parameters of the setAppID method:

Parameter

appId

Description

A string that represents the unique ID of the application issuing the password request.

Throws:

PSDKException

setReason

Description

This method specifies the reason for retrieving the password.

Mandatory

No

Default

No

Syntax

 

public void setReason (String reason)

 

The following table displays the parameters of the setReason method:

Parameter

reason

Description

A string that represents the reason for retrieving the password.

Throws

PSDKException

setConnectionPort

Description

This method specifies the port that the Java SDK will use to connect to the Credential Provider.

Mandatory

No

Default

18923

Syntax

 

public void setConnectionPort (String port)

 

The following table displays the parameters of the setConnectionPort method:

Parameter

port

Description

A string that represents the port that the SDK will use to connect to the Credential Provider.

Throws

PSDKException

setConnectionTimeout

Description

This method specifies the number of seconds that the Credential Provider will try to retrieve the password.

Mandatory

No

Default

30

Syntax

 

public void setConnectionTimeout (String timeout)

 

The following table displays the parameters of the setConnectionTimeout method:

Parameter

timeout

Description

A string that represents the connection timeout period.

Throws

PSDKException

setRequiredProperties

Description

This method specifies a list of password property values. You can specify specific password properties to return. If no properties are specified, by default all the password properties will be available to you through the PSDKPassword.getAttribute or through the direct PSDKPassword.getUserName, PSDKPassword.getAddress, PSDKPassword.getPolicyId, and PSDKPassword.getDatabase methods.

Mandatory

Yes

Default

All password properties

Syntax

 

public void setRequiredProperties (ArrayList reqProperties)

 

The following table displays the parameters of the setRequiredProperties method:

 

Parameter

reqProperties

Description

An array of strings that represents a list of password properties that will be returned with the password.

The following example shows how this method can be used to specify the PolicyID password property as a property to return with the password

 
ArrayList reqProps = new ArrayList (); 
reqProps.add (“PolicyId”);
passRequest.setRequiredProperties (reqProps);
.
.
.
System.out.println (“The password PolicyID is : “
+ password.getAttribute (“PassProps.PolicyID”));

Throws

PSDKException

setUserName

Description

This method defines search criteria according to the UserName account property.

Mandatory

No

Default

None

Syntax

 

public void setUserName(String userName)

 

The following table displays the parameters of the setUserName method:

Parameter

userName

Description

A string that represents the UserName account property in the account request.

Throws

PSDKException

setAddress

Description

This method defines search criteria according to the Address account property.

Mandatory

No

Default

None

Syntax

 

public void setAddress(String address)

 

The following table displays the parameters of the setAddress method:

Parameter

address

Description

A string that represents the Address account property in the account request.

Throws

PSDKException

setDatabase

Description

This method defines search criteria according to the Database account property.

Mandatory

No

Default

None

Syntax

 

public void setDatabase(String database)

 

The following table displays the parameters of the setDatabase method:

Parameter

database

Description

A string that represents the Database account property in the account request.

Throws

PSDKException

setPolicyID

Description

This method defines the format that will be used in the setPolicyID method.

Mandatory

No

Default

None

Syntax

 

public void setPolicyID(String policyID)

 

The following table displays the parameters of the setPolicyID method:

Parameter

policyID

Description

A string that represents the PolicyID account property in the account request.

Throws

PSDKException

setQuery

Description

This method defines a free query using account properties, including Safe, folder, and object. When this method is specified, all other search criteria (Safe/Folder/Object/UserName/Address/PolicyID/Database) are ignored and only the account properties that are specified in the query are passed to the Credential Provider in the account request.

Mandatory

No

Default

None

Syntax

 

public void setQuery(String query)

 

The following table displays the parameters of the setQuery method:

Parameter

query

Description

A string that sets the query in the account request. The query may contain the Safename, foldername, and object name in addition to one or more account properties and values, separated by ‘;’ (semi-colon).

The following example shows how this method can be used to specify one or more account properties in a request.

 
setQuery(“safe=<safe-name>;database=<db-name>”);
setQuery(“database=<db-name>”);
 
  • This method is not case-sensitive, as shown in the example above.
  • Make sure that the name or the value of the account property does not include a special character, such as ‘;’ (semi-colon). In addition, make sure that the name of the account property does not include a space.
  • If more than one account is found in the search results, an error will be returned, unless one of the accounts already exists in the Credential Provider cache and a query was issued based on the same properties.
  • You can add any other available account properties. All parameters are optional. If you specify the Safe and object, but not the folder, the ‘root’ folder will be used by default. If you do not specify the Safe and object, the Credential Provider will search in all the folders starting from the ‘root’ folder.

Throws

PSDKException

setQueryFormat

Description

This method defines the query format, which can optionally use regular expressions.

Mandatory

No

Default

PasswordQueryFormat.EXACT

Syntax

 

public void setQueryFormat(PasswordQueryFormat format)

 

The following table displays the valid values of the setQueryFormat method:

Valid values

PasswordQueryFormat.EXACT

Description

Indicates that the values set in this method and other relevant set methods are exact values. “\” values should be escaped, e.g. Folder=Root\\folder1.

Note: If you do not specify the Safe or object in the query, the Credential Provider will search as if a REGEXP query was sent, even if an EXACT query was sent.

PasswordQueryFormat.REGEXP

Description

Indicates that the values set in this method and other relevant set methods are regular expressions. To specify an exact account property match in a regular expression, the value must begin with ‘^’ and end with ‘$’.To specify free text (“wildcard”), use ‘.*’.

“\” values should be escaped twice in regular expressions, e.g. Folder=Root\\\\folder1.

In the following example, the application retrieves a database account which is part of a group (server1_OracleDB, server2_OracleDB, etc.). It can retrieve any of the group members as they all have the same password and it does not have previous knowledge of the accounts it can access. In the query it uses a regular expression in order to specify a partial address that ends with “OracleDB”, and a PolicyID with value “Oracle”:

 
passRequest.setQuery (“Address=.*OracleDB;PolicyID=^Oracle$”);
passRequest.setQueryFormat(PasswordQueryFormat.REGEXP);

Throws

PSDKException

Although some attributes can be set directly, as shown in Example 1: Request a password, the user can also specify them using the setAttribute method as shown in Example 2: Request a password with query.

setFailRequestOnPasswordChange

Description

This method determines whether the PSDKCRequestFailedOn PasswordChange exception will be thrown when a request is sent for an account that is currently being changed.

Mandatory

No

Default

False

Syntax

 

public void setFailRequestOnPasswordChange (boolean failRequestOnPasswordChange)

 

The following table displays the parameters of the setFailRequestOnPasswordChange method:

Parameter

failRequestOn PasswordChange

Description:

Determines whether the PSDKCRequestFailedOnPasswordChange exception will be thrown when a requested password is currently being changed.

Throws

PSDKException

setAttribute

Description

This method sets password request attributes. You can either use this method or any of the methods described above. The table below indicates which attributes in this method must be specified.

Mandatory

No

Default

None

Syntax

 

public void setAttribute(String attrName, String attrValue)

 

The following table displays the parameters of the setAttribute method:

Parameter

attrName

Description

A string that represents the name of the password request attribute.

Parameter

attrValue

Description

A string that represents the value of the password request attribute.

This method can set the following attributes:

Method

AppDescs.AppID

Description

The unique ID of the application issuing the password request.

Note: This parameter is required.

Acceptable Values

String

Default Value

-

Mandatory

Yes

RequiredProps

Description

Specifies the list of password properties to be retrieved with the password. You can specify specific password properties to return. If this attribute is not specified, all the password properties will be returned.

To retrieve a single property, specify: setAttribute (“RequiredProps”,”<property>”);
To retrieve multiple properties, use this attribute multiple times:

setAttribute (“RequiredProps”,”<property1>”);
setAttribute (“RequiredProps”,”<property2>”);

Acceptable Values

String

Default Value

All

Mandatory

No

Query

Description

The filter criteria for the password retrieval. The query format is:

 
Query=Safe=<safe>; 
Folder=<folder>;
Object=<password>;
Username=<username>; 
Address=<address>; PolicyID=<policyID>;
Database=<database>

You can add any other available account properties. All parameters are optional. If you specify the Safe and object, but not the folder, the ‘root’ folder will be used by default. If you do not specify the Safe and object, the Credential Provider will search in all the folders starting from the ‘root’ folder.

 
  • When specifying an empty value (e.g. PolicyID=;), the Credential Provider will search for a password with an empty value for the specified property .
  • If more than one account is found in the search results, an error will be returned, unless one of the accounts already exists in the Credential Provider cache and a query was issued based on the same properties.
  • In UNIX, enclose the query in double quotation marks, or precede each semi-colon with a backslash.
  • Make sure that the name or the value of the account property does not include a special character, such as ‘;’ (semi-colon). In addition, make sure that the name of the account property does not include a space.

Acceptable Values

String

Default Value

-

Mandatory

Yes

QueryFormat

Description

Defines the format that will be used in the Query parameter, which can optionally use regular expressions.

Acceptable Values

‘exact’ or ‘1’ – Indicates that the specified parameter values are exact values.
‘regexp’ or ‘2’ – Indicates that the specified parameter values are regular expression. To specify an exact account property match in a regular expression, the value must begin with ‘^’ and end with ‘$’.To specify free text (“wildcard”), use ‘.*’.

Default Value

exact

Mandatory

No

Reason

Description

The reason for retrieving the password, if needed.

Acceptable Values

String

Default Value

-

Mandatory

No

ConnectionParms.Port

Description

The port that is used to connect to the Credential Provider.

Acceptable Values

Number

Default Value

18923

Mandatory

No

ConnectionParms.Timeout

Description

The timeout period in seconds before a timeout message is issued when a password is requested.

Acceptable Values

Number of seconds

Default Value

30

Mandatory

No

DontSendHash

Description

 

This method is only for backward compatibility for credential file authentication with an OS user.

Whether or not the SDK will try to access the application credential file to calculate its hash value and send it to the Credential Provider in order to authenticate the user.

Acceptable Values

False – The hash will be sent to the Credential Provider.
True – Prevent the hash from being sent to the Credential Provider.
If this parameter is set to ‘True’:
1. The application does not require OS level access to the application credential file.
2. The application credential file must include the OS User name under which the application runs.

Default Value

false

Mandatory

No

FailRequestOnPasswordChange

Description

This method determines whether or not a password request will return an exception if a password change process is underway.

If this attribute is enabled and the requested password is being changed, the PSDKRequestFailedOnPasswordChange exception will be thrown.

Acceptable Values

true/false

Default Value

False

Mandatory

No

Throws

PSDKException

The following example shows how this method can be used to specify criteria that will identify the password to retrieve. You can see a full example in Example 2: Request a password with query

 
passRequest.setAttribute (“AppDescs.AppID”,<app-id>);
passRequest.setAttribute (“RequiredProps”,<Address>);
passRequest.setAttribute (“RequiredProps”,<UserName>);
passRequest.setAttribute (“Query”,”safe=<safe-name>;folder=<folder-name>;object=<object-name>”);
passRequest.setAttribute (“Reason”,<reason>);
 

The SDK will use the last configuration. For example, if the user specifies SetAttribute (Query …) and then specifies SetSafe, SetFolder, and SetObject, the specific Safe, folder and object will be taken instead of the query.

Syntax - Class: PasswordSDK

This class provides the Java Application Password SDK services.

Methods

Currently, the PasswordSDK class only provides one method to retrieve passwords:

This method is described below:

getPassword

Description

This method retrieves the specified password from the Vault.

Mandatory

Yes

Default

Syntax

No

public static PSDKPassword getPassword(PSDKPasswordRequest passRequest)

 

The following table displays the parameters of the getPassword method:

Parameter

passRequest

Description

The object that contains all the details of the password request.

Throws

PSDKException, PSDKRequestFailedOnPasswordChange

 

If the setFailRequestOnPasswordChange attribute is enabled and a password change is underway, the PSDKRequestFailedOnPasswordChange exception will be thrown.

Syntax - Class: PSDKPassword

This class represents a password object that is returned from the getPassword service.

Methods

The PSDKPassword class has the following methods:

These methods are described below.

getUserName

Description

This method returns the UserName property of the account.

If this property does not exist, or it has an empty value, or the object was disposed of, an empty string is returned.

Syntax

 

public String getUserName()

getAddress

Description

This method returns the Address property of the account.

If this property does not exist, or it has an empty value, or the object was disposed of, an empty string is returned.

Syntax

 

public String getAddress()

getPolicyID

Description

This method returns the PolicyID property of the account.

If this property does not exist, or it has an empty value, or the object was disposed of, an empty string is returned.

Syntax

 

public String getPolicyID()

getDatabase

Description

This method returns the Database property of the account.

If this property does not exist, or it has an empty value, or the object was disposed of, an empty string is returned.

Syntax

 

public String getDatabase()

getContent

Description

This method returns the password as a String object. If an error occurred or the object was disposed of, an empty string is returned.

Deprecated. Use getSecureContent() instead.

Syntax

 

public String getContent()

getSecureContent

Description

This method returns the password with enhanced security.

If the object was disposed of, returns null.

This method should always be followed by a dispose() method to clear the password held by the PSDKPassword object from memory.

Moreover, the returned object must be cleared from memory. This can be done using:

Arrays.fill(charArray, (char)0);

Note: It is recommended to use a FIPS-compliant Java Security Provider, such as Bouncy Castle.

Syntax

 

public char[] getSecureContent()

getAttribute

Description

This method returns an attribute of an account.

If this property does not exist, or it has an empty value, or the object was disposed of, an empty string is returned.

Syntax

 

public String getAttribute(String attrName)

 

The following table displays the parameters of the getAttribute method:

Parameter

attrName

Description

A string that represents the name of the account attribute.

The parameter can get the following attributes:

Attribute Name

Password

Description

The content of the password.

It is recommended to retrieve the password content using getSecureContent() described above.

PassProps.<property>

Description

The content of the password property. These properties can be retrieved with the following methods described above:

Username property – getUserName method
Address property – getAddress method
Policy ID property – getPolicyID method
Database property – getDatabase method

PasswordChangeInProcess

Description

If the FailRequestOnPasswordChange attribute was set to False and a password change is underway, this attribute will return True.

If the password is not changed when the password request is received, this attribute will return False.

Note: If the FailRequestOnPasswordChange attribute has not been enabled, the value of the PasswordChangeInProcess attribute that is returned will indicate whether a password change is underway.

Throws

PSDKException

dispose

Description

Disposes of resources used by this PSDKPassword object. The PSDKPassword object cannot be used after being disposed of because all attributes will return as empty or null.

It is preferable to manually free resources using this method rather than to rely on a finalization process which may not occur for a long period of time.

Syntax

 

public void dispose()

Throws

PSDKException

Exceptions

This section lists the exceptions that may be issued by the SDK functions.