com.ibm.websphere.wssecurity.wssapi

Class WSSUtilFactory

  • java.lang.Object
    • com.ibm.websphere.wssecurity.wssapi.WSSUtilFactory

  • public abstract class WSSUtilFactory
extends java.lang.Object

    This API has general Web Services Security utility methods for use in JAAS login modules, callback handlers, and SAML plug-ins.

    The WSSUtilFactory class can be found in the following jars:

    • plugins/com.ibm.wsfp.main.jar
    • runtimes/com.ibm.jaxws.thinclient_8.5.0.jar
    • runtimes/com.ibm.jaxws.thinclient_9.0.jar
    • dev/was_public.jar

    An instance of the WSSUtilFactory class must be obtained before its APIs can be used. The code snippet shown below demonstrates how to initialize and use the WSSUtilFactory API: 

        // get an instance of the WSSUtilFactory
    WSSUtilFactory wssuf = WSSUtilFactory.getInstance();
 
    // invoke an API from the instance
    String encoded = wssuf.encode(xmlString.getBytes());

    • Constructor Summary

      Constructors 
      Constructor and Description
      WSSUtilFactory() 

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      abstract byte[] decode(byte[] data)
      Decode Base64 encoded data.
      abstract byte[] decode(java.lang.String data)
      Decode Base64 encoded data.
      abstract java.lang.String digestPassword(byte[] nonce, java.util.Date created, char[] password)
      Calculates a password digest string.
      abstract java.lang.String digestPassword(java.lang.String nonce, java.lang.String created, char[] password)
      Calculates a password digest string.
      abstract java.lang.String encode(byte[] data)
      Base64 encode data.
      abstract java.lang.String getBase64EncodedSaml20Token(boolean compress)
      Returns the base64 encoded SAMLV2.0 token which is retrieved from the runAs subject.
      abstract java.lang.String getBase64EncodedSamlToken(java.lang.String xml, boolean compress)
      Returns the base64 encoded SAML token.
      abstract java.util.Map getCallbackHandlerProperties(javax.security.auth.callback.CallbackHandler handler)
      Get the property map from the callback handler.
      abstract java.util.Map getCallbackHandlerProperties(java.util.Map wssContext)
      Get the property map from the callback handler.
      abstract java.util.List getConsumedTokens(java.util.Map WSSContext)
      Gets the list of consumed tokens.
      abstract org.w3c.dom.Element getDOMProcessingElement(java.util.Map wssContext)
      Get the org.w3c.dom based SOAP processing element object.
      abstract java.util.Map getHTTPRequestHeaders(javax.security.auth.callback.CallbackHandler handler)
      Get the HTTP headers from an inbound SOAP request.
      abstract java.util.Map getHTTPRequestHeaders(java.util.Map wssContext)
      Get the HTTP headers from an inbound SOAP request.
      abstract java.util.Map getHTTPRequestHeaders(org.apache.axis2.context.MessageContext msgContext)
      Get the HTTP headers from an inbound SOAP request.
      static WSSUtilFactory getInstance()
      Retrieves an instance of the WSSUtilFactory.
      abstract java.security.KeyStore getKeyStore(java.lang.String keyStoreRef)
      Open a key store.
      abstract java.security.KeyStore getKeyStore(java.lang.String storeType, java.lang.String storePath, char[] storePass)
      Open a key store.
      abstract org.apache.axis2.context.MessageContext getMessageContext(javax.security.auth.callback.CallbackHandler handler)
      Get the MessageContext associated with the current request/response.
      abstract org.apache.axis2.context.MessageContext getMessageContext(java.util.Map wssContext)
      Get the MessageContext associated with the current request/response.
      abstract org.apache.axiom.om.OMElement getProcessingElement(java.util.Map wssContext)
      Get the AXIOM based SOAP processing element object.
      abstract javax.security.auth.Subject getRunAsSubject()
      getRunAsSubject returns a JAAS subject that represents the RunAs identity.
      abstract SAMLToken getSaml20Token()
      Retrieves the SAMLV2.0 token from the runAs subject.
      abstract com.ibm.wsspi.wssecurity.core.config.TokenConsumerConfig getTokenConsumerConfig(java.util.Map WSSContext)
      Gets the token consumer configuration object.
      abstract org.apache.axiom.om.OMElement getTokenElement(SecurityToken token)
      Returns the Security Token element.
      abstract SecurityToken getTokenFromSubject(javax.xml.namespace.QName qname)
      Retrieves a security token (whose value type matches the qname param) from the runAs subject.
      abstract com.ibm.wsspi.wssecurity.core.config.TokenGeneratorConfig getTokenGeneratorConfig(java.util.Map WSSContext)
      Gets the token generator configuration object.
      abstract java.util.Map getWSSContext(javax.security.auth.callback.CallbackHandler handler)
      Get the web services security context map.
      abstract java.lang.String getXML(SecurityToken token)
      Returns the XML of the token in String form

      This method will retrieve XML String representing the token from the token object.
      abstract boolean isServiceProvider()
      Identifies if the current application is a web services provider.
      abstract void setConsumedToken(java.util.Map WSSContext, java.util.List tokens)
      Sets a list consumed tokens.
      abstract void setConsumedToken(java.util.Map WSSContext, SecurityToken token)
      Sets a consumed token.
      abstract void setGeneratedToken(java.util.Map WSSContext, java.util.List tokens)
      Sets a list of generated tokens.
      abstract void setGeneratedToken(java.util.Map WSSContext, SecurityToken token)
      Sets a generated token.
      abstract boolean verifyDigestedPassword(UsernameToken unt, char[] expectedPassword)
      Verifies a digested password on a UsernameToken object.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • WSSUtilFactory

        public WSSUtilFactory()

    • Method Detail

      • getInstance

        public static WSSUtilFactory getInstance()
                                  throws WSSException
        Retrieves an instance of the WSSUtilFactory.
        Returns:
        WSSUtilFactory object
        Throws:
        WSSException - if the illegal access occurs or if the WSSUtilFactory instance is not generated.

      • encode

        public abstract java.lang.String encode(byte[] data)
        Base64 encode data.
        Parameters:
        data - bytes to be encoded
        Returns:
        base64 representation of specified byte array.

      • decode

        public abstract byte[] decode(java.lang.String data)
        Decode Base64 encoded data.
        Parameters:
        data - base64 encoded string
        Returns:
        decoded bytes

      • decode

        public abstract byte[] decode(byte[] data)
        Decode Base64 encoded data.
        Parameters:
        data - base64 encoded bytes
        Returns:
        decoded bytes

      • getKeyStore

        public abstract java.security.KeyStore getKeyStore(java.lang.String keyStoreRef)
                                            throws WSSException
        Open a key store.
        Parameters:
        keyStoreRef - centralized keystore representation
        Returns:
        KeyStore object for use with apis
        Throws:
        WSSException

      • getKeyStore

        public abstract java.security.KeyStore getKeyStore(java.lang.String storeType,
                                 java.lang.String storePath,
                                 char[] storePass)
                                            throws WSSException
        Open a key store.
        Parameters:
        storeType - key store type (type that Java security supports, ex jks, jceks, etc)
        storePath - path to key store (fully-qualified path name, or URI representation)
        storePass - key store password
        Returns:
        KeyStore object for use with apis
        Throws:
        WSSException - if the key store cannot be obtained

      • getHTTPRequestHeaders

        public abstract java.util.Map getHTTPRequestHeaders(org.apache.axis2.context.MessageContext msgContext)
        Get the HTTP headers from an inbound SOAP request.

        This api is intended to be used within a custom login module
        Parameters:
        msgContext - message context
        Returns:
        map of HTTP headers from the inbound request
        Throws:
        WSSException - if the key store cannot be obtained

      • getHTTPRequestHeaders

        public abstract java.util.Map getHTTPRequestHeaders(java.util.Map wssContext)
        Get the HTTP headers from an inbound SOAP request.

        This api is intended to be used within a custom login module
        Parameters:
        wssContext - web services security context
        Returns:
        map of HTTP headers from the inbound request

      • getHTTPRequestHeaders

        public abstract java.util.Map getHTTPRequestHeaders(javax.security.auth.callback.CallbackHandler handler)
                                             throws WSSException
        Get the HTTP headers from an inbound SOAP request.

        This api is intended to be used within a custom login module
        Parameters:
        handler - login module's callback handler
        Returns:
        map of HTTP headers from the inbound request
        Throws:
        WSSException - if the use of the handler fails

      • getWSSContext

        public abstract java.util.Map getWSSContext(javax.security.auth.callback.CallbackHandler handler)
                                     throws WSSException
        Get the web services security context map.
        Parameters:
        handler - login module's callback handler
        Returns:
        web services security context map
        Throws:
        WSSException - if the use of the handler fails

      • getMessageContext

        public abstract org.apache.axis2.context.MessageContext getMessageContext(java.util.Map wssContext)
        Get the MessageContext associated with the current request/response.
        Parameters:
        wssContext - web services security context map
        Returns:
        MessageContext associated with the current request/response

      • getMessageContext

        public abstract org.apache.axis2.context.MessageContext getMessageContext(javax.security.auth.callback.CallbackHandler handler)
                                                                   throws WSSException
        Get the MessageContext associated with the current request/response.
        Parameters:
        handler - login module's callback handler
        Returns:
        MessageContext associated with the current request/response
        Throws:
        WSSException - if the use of the handler fails

      • getCallbackHandlerProperties

        public abstract java.util.Map getCallbackHandlerProperties(java.util.Map wssContext)
        Get the property map from the callback handler.

        This api can be used to get custom properties from the currently configured callback handler without having to know what the callback handler is
        Parameters:
        wssContext - web services security context map
        Returns:
        property map from the currently configured callback handler

      • getCallbackHandlerProperties

        public abstract java.util.Map getCallbackHandlerProperties(javax.security.auth.callback.CallbackHandler handler)
                                                    throws WSSException
        Get the property map from the callback handler.

        This api can be used to get custom properties from the currently configured callback handler without having to know what the callback handler is.
        Parameters:
        handler - login module's callback handler
        Returns:
        property map from the currently configured callback handler
        Throws:
        WSSException - if the use of the handler fails

      • getProcessingElement

        public abstract org.apache.axiom.om.OMElement getProcessingElement(java.util.Map wssContext)
        Get the AXIOM based SOAP processing element object.

        This is the target token object for consumers and the parent for generators.
        Parameters:
        wssContext - web services security context map
        Returns:
        AXIOM SOAP processing element

      • getDOMProcessingElement

        public abstract org.w3c.dom.Element getDOMProcessingElement(java.util.Map wssContext)
        Get the org.w3c.dom based SOAP processing element object.

        This is the target token object for consumers and the parent for generators. This method will only return an non-null object if com.ibm.wsspi.wssecurity.domElementEnabled=true is set in the token consumer/generator custom properties (NOT callback handler)
        Parameters:
        wssContext - web services security context map
        Returns:
        org.w3c.dom.Element processing element

      • setConsumedToken

        public abstract void setConsumedToken(java.util.Map WSSContext,
                    SecurityToken token)
        Sets a consumed token.

        The token is put in the web services security context map and added to the SecurityTokenManager. This method is intended for use by a standalone token consumer login modules and not a login module that is stacked under a built-in token consumer. In the stacked scenario, the built-in consumer will do this work.
        Parameters:
        wssContext - web services security context map
        token - token that was consumed

      • setConsumedToken

        public abstract void setConsumedToken(java.util.Map WSSContext,
                    java.util.List tokens)
        Sets a list consumed tokens.

        The tokens are put in the web services security context map and are added to the SecurityTokenManager. This method is intended for use by a standalone token consumer login modules and not a login module that is stacked under a built-in token consumer. In the stacked scenario, the built-in consumer will do this work.
        Parameters:
        wssContext - web services security context map
        tokens - list of tokens that were consumed

      • setGeneratedToken

        public abstract void setGeneratedToken(java.util.Map WSSContext,
                     SecurityToken token)
        Sets a generated token.

        The token is put in the web services security context map and added to the SecurityTokenManager. This method is intended for use by a standalone token generator login modules and not a login module that is stacked over a built-in token generator. In the stacked scenario, the built-in generator will do this work.
        Parameters:
        wssContext - web services security context map
        token - token that is to be generated

      • setGeneratedToken

        public abstract void setGeneratedToken(java.util.Map WSSContext,
                     java.util.List tokens)
        Sets a list of generated tokens.

        The tokens are put in the web services security context map and are added to the SecurityTokenManager. This method is intended for use by a standalone token generator login modules and not a login module that is stacked over a built-in token generator. In the stacked scenario, the built-in generator will do this work.
        Parameters:
        wssContext - web services security context map
        tokens - list of tokens that are to be

      • getConsumedTokens

        public abstract java.util.List getConsumedTokens(java.util.Map WSSContext)
        Gets the list of consumed tokens.

        This method retrieves the list of tokens that have been consumed so far in current JAAS config stack.
        Parameters:
        wssContext - web services security context map
        Returns:
        List of SecurityToken

      • getTokenConsumerConfig

        public abstract com.ibm.wsspi.wssecurity.core.config.TokenConsumerConfig getTokenConsumerConfig(java.util.Map WSSContext)
        Gets the token consumer configuration object.

        This method retrieves the token consumer configuration object for the active token consumer.
        Parameters:
        wssContext - web services security context map
        Returns:
        token consumer configuration

      • getTokenGeneratorConfig

        public abstract com.ibm.wsspi.wssecurity.core.config.TokenGeneratorConfig getTokenGeneratorConfig(java.util.Map WSSContext)
        Gets the token generator configuration object.

        This method retrieves the token generator configuration object for the active token generator.
        Parameters:
        wssContext - web services security context map
        Returns:
        token generator configuration

      • isServiceProvider

        public abstract boolean isServiceProvider()
                                   throws com.ibm.wsspi.wssecurity.core.SoapSecurityException
        Identifies if the current application is a web services provider.

        This method determines if the current application is a web services provider or a web services client.
        Returns:
        true if a service provider, false if a client
        Throws:
        com.ibm.wsspi.wssecurity.core.SoapSecurityException

      • digestPassword

        public abstract java.lang.String digestPassword(byte[] nonce,
                              java.util.Date created,
                              char[] password)
                                         throws javax.security.auth.login.LoginException
        Calculates a password digest string.

        This method calculates a password digest string that can be used with the UsernameToken #PasswordDigest Password Type
        Parameters:
        nonce - UsernameToken nonce value in bytes
        created - UsernameToken created date
        Returns:
        the password digest string calculated from the input values
        Throws:
        javax.security.auth.login.LoginException

      • digestPassword

        public abstract java.lang.String digestPassword(java.lang.String nonce,
                              java.lang.String created,
                              char[] password)
                                         throws javax.security.auth.login.LoginException
        Calculates a password digest string.

        This method calculates a password digest string that can be used with the UsernameToken #PasswordDigest Password Type
        Parameters:
        nonce - UsernameToken nonce value, base-64 encoded
        created - UsernameToken created date in UTC String format (as it appears in the token XNL)
        Returns:
        the password digest string calculated from the input values
        Throws:
        javax.security.auth.login.LoginException

      • verifyDigestedPassword

        public abstract boolean verifyDigestedPassword(UsernameToken unt,
                             char[] expectedPassword)
                                        throws javax.security.auth.login.LoginException
        Verifies a digested password on a UsernameToken object.

        This method will verify that the comparison password is the same as the password used to make the digested password on the UsernameToken object. This is done by calculating the digest value for the comparison password using the nonce and created data in the token, then comparing it to the digested password on the UsernameToken.

        This method can only be used with UsernameTokens that have been consumed by a token consumer (UNTConsumeLoginModule or GenericIssuedTokenConsumeLoginModule). If a UsernameToken was created with a GenericSecurityTokenFactory.getFullUsernameToken method, the password in the token object (not the XML) will be in clear text regardless of the password digest setting. In this case, this method will return false unless both passwords are empty.
        Parameters:
        unt - UsernameToken containing a digested password
        expectedPassword - Password to compare
        Returns:
        true if the digested value of the comparison password equals the password on the unt object, otherwise false
        Throws:
        javax.security.auth.login.LoginException

      • getSaml20Token

        public abstract SAMLToken getSaml20Token()
        Retrieves the SAMLV2.0 token from the runAs subject.

        This method returns null if the runAs subject does not contain SAMLV2.0 token.

        Returns:
        SAMLToken

      • getTokenFromSubject

        public abstract SecurityToken getTokenFromSubject(javax.xml.namespace.QName qname)
        Retrieves a security token (whose value type matches the qname param) from the runAs subject.

        This method returns null if the runAs subject does not contain any security token with matching value type.

        Parameters:
        qname - value type to compare
        Returns:
        SecurityToken

      • getBase64EncodedSaml20Token

        public abstract java.lang.String getBase64EncodedSaml20Token(boolean compress)
        Returns the base64 encoded SAMLV2.0 token which is retrieved from the runAs subject.

        This method will return either compressed or not compressed base64 encoded SAMLV2.0 token that existed in the runAs subject. It will return null in case if there is no SAMLV2.0 token in the runAs subject.

        Parameters:
        compress - specify whether to compress the token string
        Returns:
        base64 encoded (compressed/non-compressed) SAMLV2.0 token

      • getBase64EncodedSamlToken

        public abstract java.lang.String getBase64EncodedSamlToken(java.lang.String xml,
                                         boolean compress)
        Returns the base64 encoded SAML token.

        This method will return either compressed or not compressed base64 encoded SAML token that is based on the supplied xml string.

        Parameters:
        xml - SAML token string
        compress - specify whether to compress the token string
        Returns:
        base64 encoded (compressed/non-compressed) SAML token

      • getTokenElement

        public abstract org.apache.axiom.om.OMElement getTokenElement(SecurityToken token)
        Returns the Security Token element.

        This method will retrieve the token OMElement representing the token from the token object.

        Parameters:
        token - SecurityToken
        Returns:
        SecurityToken element

      • getXML

        public abstract java.lang.String getXML(SecurityToken token)
        Returns the XML of the token in String form

        This method will retrieve XML String representing the token from the token object.

        Parameters:
        token - SecurityToken
        Returns:
        String XML form of the token element

      • getRunAsSubject

        public abstract javax.security.auth.Subject getRunAsSubject()
        getRunAsSubject returns a JAAS subject that represents the RunAs identity.
        Returns:
        a JAAS subject represents the RunAs identity.
IBM WebSphere Application ServerTM
Release 8.5