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.

Example 1: Request a password

import java.util.Arrays;
import javapasswordsdk.*;
import javapasswordsdk.exceptions.*;

public class JavaPasswordSDKSample {
    public static void main(String[] args) {
        PSDKPassword password = null;
        char[] content = null;
        try {
            PSDKPasswordRequest passRequest = new PSDKPasswordRequest();

            // Set request properties
            passRequest.setAppID(<app-id>);
            passRequest.setSafe(<safe-name>);
            passRequest.setFolder(<folder-name>);
            passRequest.setObject(<object-name>);
            passRequest.setReason(<reason>);

            // Get password object
            password = javapasswordsdk.PasswordSDK.getPassword(passRequest);

            // Get password content
            content = password.getSecureContent();

            // ...
            // Use password content here
            // Use password properties - i.e password.getUserName()
            // ...
        } catch (PSDKException ex) {
            ex.printStackTrace();
        } finally {
          if(content != null) {
            // Clean the returned object
            Arrays.fill(content, (char) 0);
          }
          if(password != null) {
			// Dispose of resources used by this PSDKPassword object
			try {
				password.dispose();
			} catch (PSDKException e) { } 
          }
        }
    }
}

Example 2: Request a password with query

import java.util.Arrays;
import javapasswordsdk.*;
import javapasswordsdk.exceptions.*;

public class JavaPasswordSDKSample {
    public static void main(String[] args) {
        PSDKPassword password = null;
        char[] content = null;
        try {
          PSDKPasswordRequest passRequest = new PSDKPasswordRequest();

          // Set request properties
          passRequest.setAppID(<app-id>);
          passRequest.setQuery(“Safe=<safe-name>;Folder=<folder-name>;Object=<object-name>”);
          passRequest.setReason(<reason>);

          // Get password object
          password = javapasswordsdk.PasswordSDK.getPassword(passRequest);

          // Get password content
          content = password.getSecureContent();

          // ...
          // Use password content here
          // Use password properties - i.e password.getUserName()
          // ...
        } catch (PSDKException ex) {
            ex.printStackTrace();
        } finally {
          if(content != null) {
            // Clean the returned object
            Arrays.fill(content, (char) 0);
          }
          if(password != null) {
			// Dispose of resources used by this PSDKPassword object
			try {
				password.dispose();
			} catch (PSDKException e) { } 
          }
        }
    }
}

Example 3: Request a password and handle a password change process using exceptions

import java.util.Arrays;
import javapasswordsdk.*;
import javapasswordsdk.exceptions.*;

public class JavaPasswordSDKSample {
    public static void main(String[] args) {
        PSDKPassword password = null;
        char[] content = null;
        try {
          PSDKPasswordRequest passRequest = new PSDKPasswordRequest();

          // Set request properties
          passRequest.setAppID(<app-id>);
          passRequest.setSafe(<safe-name>);
          passRequest.setFolder(<folder-name>);
          passRequest.setObject(<object-name>);
          passRequest.setReason(<reason>);
          passRequest.setFailRequestOnPasswordChange(true);

          boolean passRetrieved = false;
          int retryIntervalms = 1500;

          while (!passRetrieved) {
            try {
              // Sending the request to get the password
              password = javapasswordsdk.PasswordSDK.getPassword(passRequest);
              passRetrieved = true;
            } catch (PSDKRequestFailedOnPasswordChange ex) {
              try {
                Thread.sleep(retryIntervalms);
              } catch (InterruptedException e) {}
            }
          }

          // Get password content
          content = password.getSecureContent();

          // ...
          // Use password content here
          // Use password properties - i.e password.getUserName()
          // ...
        } catch (PSDKException ex) {
            ex.printStackTrace();
        } finally {
          if(content != null) {
            // Clean the returned object
            Arrays.fill(content, (char) 0);
          }
          if(password != null) {
			// Dispose of resources used by this PSDKPassword object
			try {
				password.dispose();
			} catch (PSDKException e) { }  
          }
        }
    }
}

Example 4: Request a password and handle a password change process by verifying the "PasswordChangeInProcess" attribute value

import java.util.Arrays;
import javapasswordsdk.*;
import javapasswordsdk.exceptions.*;

public class JavaPasswordSDKSample {
    public static void main(String[] args) {
        PSDKPassword password = null;
        char[] content = null;
        try {
            PSDKPasswordRequest passRequest = new PSDKPasswordRequest();

            passRequest.setAppID(<app-id>);
            passRequest.setSafe(<safe-name>);
            passRequest.setFolder(<folder-name>);
            passRequest.setObject(<object-name>);
            passRequest.setReason(<reason>f);
            passRequest.setFailRequestOnPasswordChange(false); // Optional, this is the default value

            boolean passRetrieved = false;
            int retryIntervalms = 1500;

            while (!passRetrieved) {
                // Sending the request to get the password
                password = javapasswordsdk.PasswordSDK.getPassword(passRequest);

                if (password.getAttribute("PasswordChangeInProcess").equals("true")) {
                    try {
                        Thread.sleep(retryIntervalms);
                    } catch (InterruptedException e) {
                    }
                } else {
                    passRetrieved = true;
                }
            }

            // Get password content
            content = password.getSecureContent();

            // ...
            // Use password content here
            // Use password properties - i.e password.getUserName()
            // ...
        } catch (PSDKException ex) {
            ex.printStackTrace();
        } finally {
            if (content != null) {
                // Clean the returned object
                Arrays.fill(content, (char) 0);
            }
            if (password != null) {
                // Dispose of resources used by this PSDKPassword object
                try {
                    password.dispose();
                } catch (PSDKException e) { }  
            }
        }
    }
}

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:

PSDKPasswordRequest ()

This class has the following methods:

setSafe
setFolder
setObject
setAppID
setReason
setConnectionPort
setConnectionTimeout
setRequiredProperties
setUserName
setAddress
setDatabase
setPolicyID
setQuery
setQueryFormat
setFailRequestOnPasswordChange
setAttribute

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

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

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

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.

This parameter is required.

Mandatory

Yes

Default

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

Default

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

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

Default

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

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

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

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

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

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. As a best practice, always add a Safe and an Object or Username to your query.

Throws

PSDKException

setQueryFormat

Description

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

Mandatory

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

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

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.

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

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. As a best practice, always add a Safe and an Object or Username to your query.

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

Reason

Description

The reason for retrieving the password, if needed.

Acceptable Values

String

Default Value

Mandatory

ConnectionParms.Port

Description

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

Acceptable Values

Number

Default Value

18923

Mandatory

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

Mandatory

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’:

The application does not require OS level access to the application credential file.
The application credential file must include the OS User name under which the application runs.

Default Value

false

Mandatory

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

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:

getPassword

This method is described below:

getPassword

Description

This method retrieves the specified password from the Vault.

Mandatory

Yes

Default

Syntax

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:

getUserName
getAddress
getPolicyID
getDatabase
getContent
getSecureContent
getAttribute
dispose

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);

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

PSDKException

This exception is thrown by the following constructors and methods:

Class:	PSDKPasswordRequest
Constructor:	PSDKPasswordRequest
Methods:	setSafe, setFolder, setObject, setAppID, setReason, setConnectionPort, setConnectionTimeout, setRequiredProperties, setAttribute, setPolicyId, setDatabase, setUserName, setAddress, setQuery, setQueryFormat, setFailRequestOnPasswordChange
Class:	PasswordSDK
Methods:	getPassword
Class:	PSDKPassword
Methods:	getAttribute

PSDKRequestFailedOnPasswordChange

This exception is thrown by the following methods:

Class	PasswordSDK
Methods:	getPassword