Developing a password callback handler for WS-Security

In Liberty, password callback handlers can be used in many WS-Security scenarios to retrieve passwords. For example, passwords can be retrieved for generating UsernameTokens, opening keystores, or accessing private keys. A password callback handler is required for the provider when you use PasswordDigest. A password callback handler must be packaged as a user feature in Liberty.

1. Develop a password callback handler.
   The following example shows a callback handler:

   package com.ibm.ws.wssecurity.example.cbh;
   
   import java.util.HashMap;
   import java.util.Map;
   import javax.security.auth.callback.Callback;
   import javax.security.auth.callback.CallbackHandler;
   import org.apache.wss4j.common.ext.WSPasswordCallback;
   
   public class SamplePasswordCallback implements CallbackHandler {
   
     private Map<String, String> userPasswords =  new HashMap<String, String>();
     private Map<String, String> keyPasswords = new HashMap<String, String>();
     public SamplePasswordCallback() {
       // some example user passwords
       userPasswords.put("user1", "user1pswd");
       userPasswords.put("admin", "adminpswd");
       // some example key passwords
       keyPasswords.put("alice",  "keypwsd");
       keyPasswords.put("bob",   "keypswd");
     }
     public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
       for (int i = 0; i < callbacks.length; i++) {
         WSPasswordCallback pwcb = (WSPasswordCallback)callbacks[i];
         String id = pwcb.getIdentifier();
         String pass = null;
         switch (pwcb.getUsage()) {
           case WSPasswordCallback.USERNAME_TOKEN_UNKNOWN:
           case WSPasswordCallback.USERNAME_TOKEN:
             pass = userPasswords.get(id);
             pwcb.setPassword(pass);
             break;
           case WSPasswordCallback.SIGNATURE:
           case WSPasswordCallback.DECRYPT:
             pass = keyPasswords.get(id);
             pwcb.setPassword(pass);
             break;
         }
       }
     }
   }

   In version 22.0.0.7 and earlier, replace org.apache.wss4j.common.ext.WSPasswordCallback in the previous example with org.apache.ws.security.WSPasswordCallback.

2. Create a MANIFEST.MF file for the callback handler.
   The following example shows a MANIFEST.MF file:

   Manifest-Version: 1.0
   Bnd-LastModified: 1359415594428
   Build-Identifier: SNAPSHOT-Mon Jan 28 17:26:34 CST 2013
   Bundle-Copyright: The Program materials contained in this file are IBM
   copyright materials. 5724-I63, 5724-J08, 5724-H89, 5724-H88, 5655-W65
   Copyright International Business Machines Corp. 1999, 2012 All Rights
   Reserved * Licensed Materials - Property of IBM US Government Users
   Restricted Rights - Use, duplication or disclosure restricted by GSA ADP
   Schedule Contract with IBM Corp.
   Bundle-Description: An PasswordCallbackHandler; version=1.0.0
   Bundle-ManifestVersion: 2
   Bundle-Name: wssecuritycbh
   Bundle-SymbolicName: com.ibm.ws.wssecurity.example.cbh
   Bundle-Vendor: IBM
   Bundle-Version: 1.0.0
   Created-By: 1.6.0 (IBM Corporation)
   Export-Package: com.ibm.ws.wssecurity.example.cbh;uses:="com.ibm.websphe
   re.ras.annotation,javax.security.auth.callback";version="1.0.0"
   Import-Package: com.ibm.websphere.ras,com.ibm.websphere.ras.annotation,c
   om.ibm.ws.ffdc,javax.security.auth.callback,org.apache.ws.security;version="[1.6,2)"
   Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version>=1.6))"
   Tool: Bnd-2.1.0.20120920-170235
   WS-TraceGroup: WSSecurity

3. Package the callback handler into a JAR file.
   Create a JAR file with the callback handler class and the MANIFEST.MF file that you created in the previous steps.
   The following example shows the contents of a sample JAR file that is called SampleCbh.jar:

   META-INF/MANIFEST.MF
   com/ibm/ws/wssecurity/example/cbh/SamplePasswordCallback.class

4. Create a feature manifest file.
   The following example shows a sample feature manifest file that is called wsseccbh-1.0.mf:

   Subsystem-ManifestVersion: 1
   Subsystem-SymbolicName: wsseccbh-1.0; visibility:=public
   Subsystem-Version: 1.0.0
   Subsystem-Content: com.ibm.ws.wssecurity.example.cbh; version="[1,1.0.100)";
       location:="lib/"; type="osgi.bundle"; start-phase:=APPLICATION_EARLY
    
   Subsystem-Type: osgi.subsystem.feature
   IBM-Feature-Version: 2
   
   IBM-API-Package: com.ibm.ws.wssecurity.example.cbh; version="1.0"; type="internal"

5. Install the callback handler as a user feature in Liberty.
   Copy the callback handler JAR file and the feature manifest file to the Liberty user directory.
   The following example shows where to copy the files:

   build.image/wlp/usr/extension/lib/SampleCbh.jar
   build.image/wlp/usr/extension/lib/features/wsseccbh-1.0.mf

6. Configure the callback handler as a user feature in the server.xml file.
   Define the callback handler as a user feature in the server.xml file.
   The following example shows how to define the callback handler as a user feature:

   <featureManager>
     <feature>usr:wsseccbh-1.0</feature>
     <feature>servlet-3.0</feature>
     <feature>appSecurity-2.0</feature>
     <feature>jaxws-2.2</feature>
     <feature>wsSecurity-1.1</feature>
   </featureManager>