Home » wss4j-src-1.5.7 » org.apache.ws.security.handler » [javadoc | source]
org.apache.ws.security.handler
public class: WSHandlerConstants [javadoc | source]
java.lang.Object
   org.apache.ws.security.handler.WSHandlerConstants
This class defines the names, actions, and other string for the deployment data of the WSS handler. Both the Axis handler as well as the JAX-RPC handler use this class.
Field Summary
public static final  String ACTION    The action parameter. The handlers use the value of this parameter to determine how to process the SOAP Envelope. For example in a Axis WSDD file:
<handler type="java:org.apache.ws.axis.security.WSDoAllSender">
<parameter name="action" value="UsernameToken"/>
...
orders the handler to attach a UsernameToken to the SOAP enevelope. It is a blank separated list of actions to perform.

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.ACTION, WSHandlerConstants.USERNAME_TOKEN);
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting) 
public static final  String SEND     
public static final  String RECEIVE     
public static final  String NO_SECURITY    Perform nothing. 
public static final  String USERNAME_TOKEN    Perform a UsernameToken identification only. 
public static final  String SAML_TOKEN_UNSIGNED    Perform a SAML Token identification. 
public static final  String SAML_TOKEN_SIGNED     
public static final  String SIGNATURE    Perform Signature. The signature specific parameters define how to sign, which keys to use, and so on 
public static final  String ENCRYPT    Perform Encryption. The encryption specific parameters define how to encrypt, which keys to use, and so on. 
public static final  String TIMESTAMP    Add a timestamp to the security header. 
public static final  String NO_SERIALIZATION    Supress the serialization of the SOAP message.

Usually the handler serializes the processed SOAP message into a string and sets it into the Axis message context as new current message. To supress this action, define this action. In this case the handler stores the processed SOAP message as Document in the Axis message context with the property name SND_SECURITY.

A chained handler can retrieve the SOAP message and process it. The last handler in the chain must set the processed SOAP message as current message in Axis message context. 

public static final  String SIGN_WITH_UT_KEY    Use this to use a specific signature mechanism for .Net. This signature mechanism uses data from the username token and a well defined constant string and constructs a signature key. 
public static final  String SND_SECURITY    This is an interal property name to support handler chaining. The Axis WSS4J handlers use this message context property to hand over the SOAP partially processed envelope document to the next WSS4J handler in the chain. 
public static final  String ACTOR    The actor name of the wsse:Security header.

If this parameter is omitted, the actor name is not set. Please refer to org.apache.axis.Constants#ATTR_ACTOR and org.apache.axis.Constants#ATTR_ROLE about the parameter names. They are set to "actor" and "role" respectively.

The value of the actor or role has to match the receiver's setting or may contain standard values.

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.ACTOR, "ActorName");
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting).
    Also see:
    org.apache.axis.Constants#URI_SOAP11_NEXT_ACTOR
    org.apache.axis.Constants#URI_SOAP12_NEXT_ROLE
 
public static final  String ROLE    The role name of the wsse:Security header. This is used for SOAP 1.2. Refer also to #ACTOR
public static final  String MUST_UNDERSTAND    Sets the mustUnderstand flag.

If the parameter has the value 1 or true the mustUnderstand is set. The values 0 or false supress the flag.

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.MUST_UNDERSTAND, "false");
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting).

The default setting is true

Please refer to org.apache.axis.Constants#ATTR_MUST_UNDERSTAND about the parameter name ("mustUnderstand"). 

public static final  String USER    The user's name. It is used differently by the WS Security functions.
  • The UsernameToken function sets this name in the UsernameToken.
  • The Signing function uses this name as the alias name in the keystore to get user's certificate and private key to perform signing.
  • The encryption functions uses this parameter as fallback if #ENCRYPTION_USER is not used.
It is also possible to set the user's name and the according password via the call function, for example:
...
call.setUsername("name");
call.setPassword("WSS4Java");
...
The user parameter in the deployment descritor (WSDD) file overwrites the application's setting.

For an additional way to set the password refer to #PW_CALLBACK_CLASS and #PW_CALLBACK_REF .

If the security functions uses the username from the message context, it clears the username from the message context after they copied it. This prevents sending of the username in the HTTP header.

In this case the HTTP authentication mechansisms do not work anymore. User authentication shall be done via the username token or the certificate verification of the signature certificate. 

public static final  String PW_CALLBACK_CLASS    The Axis WSS4J handlers provide several ways to get the password required to construct a username token or to sign a message. In addition the callback class may check if a username/password combination is valid. Refer to the documentation of org.apache.ws.security.WSPasswordCallback for more information about this feature.
  • A class that implements a callback interface (see below). The handler loads this class and calls the callback method. This class must have a public default constructor with not parameters.
  • The application (or a preceeding handler) sets a reference to an object that implements the callback interface
  • The application sets the password directly using the setPassword function of the Call.
The callback class or callback object shall implement specific password getter methods, for example reading a database or directory.

The handler first checks if it can get a the password via a callback class. If that fails it checks if it can get the password from the object reference, if that also fails the handler tries the password property.

The following parameter defines a class that implements a callback handler interface. The handler loads the class and calls the callback handler method to get the password. The callback class needs to implement the javax.security.auth.callback.CallbackHandler interface.

The callback function javax.security.auth.callback.CallbackHandler#handle(javax.security.auth.callback.Callback[]) gets an array of org.apache.ws.security.WSPasswordCallback objects. Only the first entry of the array is used. This object contains the username/keyname as identifier. The callback handler must set the password or key associated with this identifier before it returns.

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.PW_CALLBACK_CLASS, "PWCallbackClass");
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting).

Refer also to comment in #USER about HTTP authentication functions. 

public static final  String PW_CALLBACK_REF    An application may set an object reference to an object that implements the javax.security.auth.callback.CallbackHandler interface. Only the application can set this property using:
call.setProperty(WSHandlerConstants.PW_CALLBACK_REF, anPWCallbackObject);
Refer to #PW_CALLBACK_CLASS for further information about password callback handling and the priority of the different methods.

Note: every handler that preceeds this handler in the chain can set this property too. This may be useful on the server side. 

public static final  String ENCRYPTION_USER    The user's name for encryption.

The encryption functions uses the public key of this user's certificate to encrypt the generated symmetric key.

If this parameter is not set, then the encryption function falls back to the #USER parameter to get the certificate.

If only encryption of the SOAP body data is requested, it is recommended to use this parameter to define the username. The application can then use the standard user and password functions (see example at #USER to enable HTTP authentication functions.

Encryption only does not authenticate a user / sender, therefore it does not need a password.

Placing the username of the encryption certficate in the WSDD is not a security risk, because the public key of that certificate is used only.

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.ENCYRPTION_USER, "encryptionuser");
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting). 
public static final  String USE_REQ_SIG_CERT    Specifying this name as #ENCRYPTION_USER triggers a special action to get the public key to use for encryption.

The handler uses the public key of the sender's certificate. Using this way to define an encryption key simplifies certificate management to a large extend. 

public static final  String ENC_CALLBACK_CLASS    This parameter works in the same way as #PW_CALLBACK_CLASS but the Axis WSS4J handler uses it to get the key associated with a key name. 
public static final  String ENC_CALLBACK_REF    This parameter works in the same way as #PW_CALLBACK_REF but the Axis WSS4J handler uses it to get the key associated with a key name. 
public static final  String ENC_KEY_NAME    Text of the key name that needs to be sent 
public static final  String SIG_PROP_FILE    The name of the crypto property file to use for SOAP Signature.

The classloader loads this file. Therefore it must be accessible via the classpath.

To locate the implementation of the Crypto interface implementation the property file must contain the property org.apache.ws.security.crypto.provider. The value of this property is the classname of the implementation class.

The following line defines the standard implementation:

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
The other contents of the property file depend on the implementation of the Crypto interface implementation.

The property file of the standard implementation org.apache.ws.security.components.crypto.Merlin uses the following properties:

org.apache.ws.security.crypto.provider
org.apache.ws.security.crypto.merlin.file
org.apache.ws.security.crypto.merlin.keystore.type
org.apache.ws.security.crypto.merlin.keystore.provider
org.apache.ws.security.crypto.merlin.keystore.password
org.apache.ws.security.crypto.merlin.keystore.alias
org.apache.ws.security.crypto.merlin.cert.provider
The entries are:
  • org.apache.ws.security.crypto.provider see description above
  • org.apache.ws.security.crypto.merlin.file The path to the keystore file. At first the classloader tries to load this file, if this fails the implementations performs a file system lookup.
  • org.apache.ws.security.crypto.merlin.keystore.type The keystore type, for example JKS for the Java key store. Other keystore type, such as pkcs12 are also possible but depend on the actual Crypto implementation.
  • org.apache.ws.security.crypto.merlin.keystore.password The password to read the keystore. If this property is not set, then the pwcallbackproperty must be defined.
The application may set this parameter using the following method:
call.setProperty(WSHandlerConstants.SIG_PROP_FILE, "myCrypto.properties");
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting).

If a property file is not set and a signature is requested, the handler throws an AxisFault

public static final  String SIG_PROP_REF_ID    The key that hold the refernce of the java.util.Properties object holding complete info about signature Crypto implementation. This should contain all information that would contain in an equivalent .properties file which includes the Crypto implementation class name. Refer to documentation of #SIG_PROP_FILE
public static final  String RECV_RESULTS    The WSDoAllReceiver handler stores a result Vector in this property.

The vector contains WSDoAllReceiverResult objects for each chained WSDoAllReceiver handler. 

public static final  String DEC_PROP_FILE    The name of the crypto propterty file to use for SOAP Decryption.

Refer to documentation of #SIG_PROP_FILE .

Refer to #SIG_PROP_FILE for a detail description about the format and how to use this property file.

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.DEC_PROP_FILE, "myCrypto.properties");
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting).

If this parameter is not used, but the signature crypto property file is defined (combined Encryption/Signature action), then the encryption function uses that file. Otherwise the handler throws an AxisFault

public static final  String DEC_PROP_REF_ID    The key that hold the refernce of the java.util.Properties object holding complete info about decryption Crypto implementation. This should contain all information that would contain in an equivalent .properties file which includes the Crypto implementation class name. Refer to documentation of #DEC_PROP_FILE
public static final  String PASSWORD_TYPE    Specific parameter for UsernameToken action to define the encoding of the password.

The parameter can be set to either WSConstants#PW_DIGEST or to WSConstants#PW_TEXT .

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.PASSWORD_TYPE, WSConstants.PW_DIGEST);
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting).

The default setting is PW_DIGEST. 

public static final  String HANDLE_CUSTOM_PASSWORD_TYPES    This variable controls whether types other than PasswordDigest or PasswordText are allowed when processing UsernameTokens. By default this is set to false so that the user doesn't have to explicitly reject custom token types in the callback handler. 
public static final  String ADD_UT_ELEMENTS    Parameter to generate additional elements in UsernameToken.

The value of this parameter is a list of element names that are added to the UsernameToken. The names of the list a separated by spaces.

The list may containe the names nonce and created only. Use this option if the password type is passwordText and the handler shall add the Nonce and/or Created elements. 

public static final  String SIG_KEY_ID    Defines which key identifier type to use. The WS-Security specifications recommends to use the identifier type IssuerSerial. For possible signature key identifier types refer to #keyIdentifier . For signature IssuerSerial and DirectReference are valid only.

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.SIG_KEY_ID, "DirectReference");
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting). 
public static final  String SIG_ALGO    Defines which signature algorithm to use.

The application may set this parameter using the following method:

call.setProperty(
WSHandlerConstants.SIG_ALGO,
"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
);
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting). 
public static final  String SIG_DIGEST_ALGO    Defines which signature digest algorithm to use.

The application may set this parameter using the following method:

call.setProperty(
WSHandlerConstants.SIG_DIGEST_ALGO, "http://www.w3.org/2001/04/xmlenc#sha256"
);
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting). 
public static final  String SIGNATURE_PARTS    Parameter to define which parts of the request shall be signed.

Refer to #ENCRYPTION_PARTS for a detailed description of the format of the value string.

If this parameter is not specified the handler signs the SOAP Body by default.

The WS Security specifications define several formats to transfer the signature tokens (certificates) or references to these tokens. Thus, the plain element name Token signs the token and takes care of the different format.

To sign the SOAP body and the signature token the value of this parameter must contain:

<parameter name="signatureParts"
value="{}{http://schemas.xmlsoap.org/soap/envelope/}Body; Token" />
To specify an element without a namespace use the string Null as the namespace name (this is a case sensitive string)

If there is no other element in the request with a local name of Body then the SOAP namespace identifier can be empty ({}). 

public static final  String ENC_PROP_FILE    The name of the crypto propterty file to use for SOAP Encryption.

Refer to documentation of #SIG_PROP_FILE .

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.ENC_PROP_FILE, "myCrypto.properties");
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting).

If this parameter is not used, but the signature crypto property file is defined (combined Encryption/Signature action), then the encryption function uses signature property file. Otherwise the handler throws an AxisFault

public static final  String ENC_PROP_REF_ID    The key that hold the refernce of the java.util.Properties object holding complete info about encryption Crypto implementation. This should contain all information that would contain in an equivalent .properties file which includes the Crypto implementation class name. Refer to documentation of #DEC_PROP_FILE
public static final  String ENC_KEY_ID    Defines which key identifier type to use. The WS-Security specifications recommends to use the identifier type IssuerSerial. For possible encryption key identifier types refer to #keyIdentifier . For encryption IssuerSerial, X509KeyIdentifier, DirectReference, Thumbprint, SKIKeyIdentifier, and EmbeddedKeyName are valid only.

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.ENC_KEY_ID, "X509KeyIdentifier");
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting). 
public static final  String ENC_SYM_ALGO    Defines which symmetric encryption algorithm to use. WSS4J supports the following alorithms: WSConstants#TRIPLE_DES , WSConstants#AES_128 , WSConstants#AES_256 , and WSConstants#AES_192 . Except for AES 192 all of these algorithms are required by the XML Encryption specification.

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.ENC_SYM_ALGO, WSConstants.AES_256);
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting). 
public static final  String ENC_KEY_TRANSPORT    Defines which algorithm to use to encrypt the generated symmetric key. Currently WSS4J supports WSConstants#KEYTRANSPORT_RSA15 only.

The application may set this parameter using the following method:

call.setProperty(WSHandlerConstants.ENC_KEY_TRANSPORT, "RSA15");
However, the parameter in the WSDD deployment file overwrites the property setting (deployment setting overwrites application setting). 
public static final  String ENCRYPTION_PARTS    Parameter to define which parts of the request shall be encrypted.

The value of this parameter is a list of semi-colon separated element names that identify the elements to encrypt. An encryption mode specifier and a namespace identification, each inside a pair of curly brackets, may preceed each element name.

The encryption mode specifier is either {Content} or {Element}. Please refer to the W3C XML Encryption specification about the differences between Element and Content encryption. The encryption mode defaults to Content if it is omitted. Example of a list:

<parameter name="encryptionParts"
value="{Content}{http://example.org/paymentv2}CreditCard;
{Element}{}UserName" />
The the first entry of the list identifies the element CreditCard in the namespace http://example.org/paymentv2, and will encrypt its content. Be aware that the element name, the namespace identifier, and the encryption modifier are case sensitive.

The encryption modifier and the namespace identifier can be ommited. In this case the encryption mode defaults to Content and the namespace is set to the SOAP namespace.

An empty encryption mode defaults to Content, an empty namespace identifier defaults to the SOAP namespace. The second line of the example defines Element as encryption mode for an UserName element in the SOAP namespace.

To specify an element without a namespace use the string Null as the namespace name (this is a case sensitive string)

If no list is specified, the handler encrypts the SOAP Body in Content mode by default. 

public static final  String SAML_PROP_FILE    The name of the SAML Issuer factory property file. The classloader loads this file. Therefore it must be accessible via the classpath. 
public static final  String TTL_TIMESTAMP    Time-To-Live is the time difference between creation and expiry time in the WSS Timestamp. The time-to-live in seconds. After this time the SOAP request is invalid (at least the security data shall be treated this way).

If this parameter is not defined, contains a value less or equal zero, or an illegal format the handlers use a default TTL of 300 seconds (5 minutes). 

public static final  String ENABLE_SIGNATURE_CONFIRMATION    Whether to enable signatureConfirmation or not By default signatureConfirmation is enabled 
public static final  String TIMESTAMP_PRECISION    Should timestamps have precision in milliseconds 
public static final  String TIMESTAMP_STRICT    Set the value of this parameter to true to enable strict timestamp handling. Strict Timestamp handling: throw an exception if a Timestamp contains an Expires element and the semantics of the request are expired, i.e. the current time at the receiver is past the expires time. 
public static  Map keyIdentifier    Define the parameter values to set the key identifier types. These are: #SIG_KEY_ID #ENC_KEY_ID
public static final  String SEND_SIGV     
public static final  String SIG_CONF_DONE     
Methods from java.lang.Object:
equals,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait