WebPasswordSafe Developer Guide

I. Introduction

This developer guide covers customizing reports, internationalization, using optional plugins, developing custom plugins, and integrating these into the build process of WebPasswordSafe.

II. General Integrating Source Code Into Build Process

• Copy main source code under /webpasswordsafe/src/main/java/* using full package/directory structure
• Copy JTest source code under /webpasswordsafe/src/test/java/* using full package/directory structure
• Follow Build and Deploy directions as in Administrator Guide

III. Optional Plugins

RsaSecurIDAuthenticator, EsapiDigester, and EsapiEncryptor are some optional plugins that are included in the download. If you want to use any of these, you need to copy from /webpasswordsafe/src/optional/java/* into the appropriate source directories (see above) as well as edit the /webpasswordsafe/pom.xml file to include their dependencies. Lastly edit the various configuration files to reference them (see Administrator Guide).

Here is the appropriate Maven command to integrate the RSA plugin:

• mvn install:install-file -DgroupId=com.rsa.authagent -DartifactId=authapi -Dversion=8.1.0 -Dpackaging=jar -Dfile=authapi.jar

If using ESAPI for encryption:

1. Copy the contents of your /configuration/esapi resources directory (downloaded from esapi-2.0.1-configuration.zip) into /webpasswordsafe/src/main/resources/esapi or if directory is kept outside the web application, edit /webpasswordsafe/war/WEB-INF/encryption.properties and change encryptor.esapi.useClasspath=false and encryptor.esapi.resourceDir=<full path to directory>
2. Edit ESAPI.properties and verify all of the Encryptor.* values, notably EncryptionKeyLength (128 or 256) and MasterKey and MasterSalt values
3. Generate new MasterKey and MasterSalt values by invoking from the /webpasswordsafe directory:
   • mvn exec:java -Dexec.mainClass="org.owasp.esapi.reference.crypto.JavaEncryptor" -Dexec.classpathScope=runtime -Dorg.owasp.esapi.resources=src/main/resources/esapi

IV. Custom Plugins

You can write your own implementations to the WebPasswordSafe plugins using Java and integrate them into the build process similar to the optional plugins (see above). Below discusses the interface requirements of each plugin.

1. Audit Logger Plugin

• Implement: net.webpasswordsafe.server.plugin.audit.AuditLogger
• Override: public void log(Date eventdate, String username, String ipaddress, String action, String target, boolean status, String message)

2. Authentication Plugin

• Implement: net.webpasswordsafe.server.plugin.authentication.Authenticator
• Override: public boolean authenticate(String username, String password)

3. Role Retriever Plugin

• Implement: net.webpasswordsafe.server.plugin.authentication.RoleRetriever
• Override: public Set<Role> retrieveRoles(User user)
• Note: You will want to pay attention to the available roles defined in net.webpasswordsafe.common.util.Constants

4. Authorization Plugin

• Implement: net.webpasswordsafe.server.plugin.authorization.Authorizer
• Override: public boolean isAuthorized(User user, String action)
• Note: You will want to pay attention to the available roles and functions defined in net.webpasswordsafe.common.util.Constants

5. Password Generator Plugin

• Implement: net.webpasswordsafe.server.plugin.generator.PasswordGenerator
• Override: public String generatePassword()

6. Encryption - Digester Plugin

• Implement: net.webpasswordsafe.server.plugin.encryption.Digester
• Override: public String digest(String clearText)
• Override: public boolean check(String clearText, String cryptedText)

7. Encryption - Encryptor Plugin

• Implement: net.webpasswordsafe.server.plugin.encryption.Encryptor
• Override: public String encrypt(String clearText)
• Override: public String decrypt(String cryptedText)

V. Customizing Reports

Reports in WebPasswordSafe are developed using JasperReports. You can find the .jrxml files in /webpasswordsafe/war/WEB-INF/reports/ from which you can edit and customize the look of them and in some cases the data contained in them. Be careful however that the look-and-feel customizations you make for either PDF or CSV format doesn't break the other format (if you care). If you change data, be careful that the appropriate security controls and authorization are in place. Lastly, the reports configuration can be changed in /webpasswordsafe/war/WEB-INF/webpasswordsafe-reports.xml including access controls, parameters, and how they are presented on the client-side to the user.

VI. Internationalization (i18n)

All text strings in the WebPasswordSafe client-side GUI are extracted out into reusable property bundles for easy customization and flexibility adding new language support. The default is US English.

To add a new language:

1. Create new file /webpasswordsafe/src/main/java/net/webpasswordsafe/client/i18n/TextMessages_{locale code}.properties using UTF-8 charset file format
2. Edit file to include all key=value pairs for each tag representing a specific text string used in the application as the key and the value being the localized text string or date format (use TextMessages_zh.properties as a template)
3. For reports do the same with /webpasswordsafe/src/main/resources/i18n_{locale code}.properties
4. Edit /webpasswordsafe/src/main/java/net/webpasswordsafe/WebPasswordSafe.gwt.xml uncommenting the "locale" extended-property setting the values to the locale code(s) above
5. Follow Build and Deploy directions as in Administrator Guide
6. To override the default locale when using WebPasswordSafe, add ?locale={locale code} to the end of the URL