WS Security API

Predefined Classes for WS Security

WSPolicy

Constructor

WSPolicy (mixed policy)

Construct a new WSPolicy Object.
A policy can be one of following.

1. XML string representing the corresponding policy.

2. Array

An array of options can be specified using the syntax given below.
array("security"=>array of security options)

When using WSPolicy, you can use a policy XML file to configure the security options to be used. When the user has a policy file, he or she can create a policy object using an XML string or a DOM node corresponding to that policy file. This is the recommended scenario. In addition to that, the WSO2 WSF/PHP security API gives you the ability to configure a minimum set of security features by using an options array that is accepted by the WSPolicy constructor. The following is a description of the options that can be provided in the options array. Examples will be provided on the policy files later in this document.

Option Data Type Value Domain Default Value Description
sign string | boolean TRUE | "X509" FALSE Whether to sign the XML message or not. By default signing is not enabled.
If specified "sign"=>TRUE, the body part of the SOAP message will be signed using the X509 standard.
Signing will be done on the body part of the message. To sign other parts of the message, a policy file should be used.
encrypt string | boolean TRUE | "X509"
FALSE Whether to encrypt the XML message or not. By default encryption is not enabled.
If specified "encrypt"=>TRUE, the body part of the SOAP message will be encrypted using the X509 standard.
Encrypting will be done on the body part of the message. To encrypt headers, a policy file should be used.
algorithmSuite string corresponds to Security Policy spec 7.1 [Algorithm Suite] definitions
"Basic256Rsa15" The symmetric algorithm and asymmetric algorithm will be derived from the algorithmSuite string.
layout string "Strict" | "Lax" "Strict" Defines the element order in the security header. These are defined in the WS Security Policy Specification 1.1 section 7.7
includeTimeStamp bool TRUE FALSE If specified TRUE and the user provided the ttl (time to live ) value when providing the security token object, the timestamp will be used.
protectionOrder string "EncryptBeforeSigning" | "SignBeforeEncrypt" "SignBeforeEncrypt" The order in which integrity and confidentiality are applied to the message in cases where both integrity and confidentiality are required.
useUsernameToken boolean TRUE FALSE If the necessary options are provided with the WSSecurityToken object, and if "useUsernameToken"=>TRUE , then the UsernameToken will be enabled.
securityTokenReference string "IssuerSerial" | "KeyIdentifier"|"EmbeddedToken"
|"Thumbprint"| "Direct"
"KeyIdentifier"
Defines how the security tokens are sent when using encryption.
If you wish to have security token references when signing, you should provide the appropriate policy file.
encryptSignature boolean TRUE FALSE If specified TRUE the message signature (the primary signature) must be encrypted.
binding string "Asymmetric" | "Symmetric" "Asymmetric" By default, all security bindings will be Asymmetric meaning that public key security options will be used. By setting the binding option to "Symmetric" symmetric key usage can be enforced.
inMessagePolicy mixed
array or string
NONE NONE This option is only useful in specifying operation level policies. When considering an operation, the policies can be specified for the incoming message as well as for the outgoing message. In this case the policy object can be constructed by specifying an array as follows.
$policy = new WSPolicy(
array("inMessagePolicy"=>$sec_array,
"outMessagePolicy"=>$sec_array));
outMessagePolicy mixed
array or string
NONE NONE This is exactly the same as the option "inMessagePolicy". Another code snippet using a policy xml strings.

$policy = new WSPolicy(
array("inMessagePolicy"=>$in_policy_str,
"outMessagePolicy"=>$out_policy_str));

WSSecurityToken

A PHP level object that logically represents security properties. This object will be used to specify the security properties from the client or service.

WSSecurityToken::__construct(array of options)

Options that can be provided in the options array are detailed in the following table.

Option Data Type Value Domain Default Value Description
user string string none Username
certificate string string none producer's certificate (public key). This should be loaded using the function ws_get_cert_from_file(). This key is send to the receiver with security headers.
passwordType string "PlainText" |"Digest" Digest Password type to be used in UsernameToken
password string string none Producer's password to be used for UsernameToken
privateKey string string none Producer's private key. Should be loaded using the function ws_get_key_from_file()
receiverCertificate string string
none Receiver's certificate. Should be loaded from the function ws_get_cert_from_file()
ttl
int
int
360 The time period within which the message would be valid (time to live) in seconds
passwordCallback string string none Name of the password callback function, which is a user defined function that accepts a username and returns the corresponding password. The signature of this function should be like
string function_name(string username[,mixed args]). The args is an optional argument in case the user was to pass additional data to the function that would be necessary to obtain the password.
passwordCallbackData mixed mixed none Any optional arguments that must be available in the passwordCallback function can be set using this option.
replayDetectionCallback string string none Name of the replay detection callback function, which is a user defined function that accepts a message_id, time stamp and any optional arguments set using replayDectionCallbackData. The functions implementation should be such that it should store all received unique message ids and timestamps. If an existing message id + timestamp is encountered, it should return false, indicating a replay, otherwise it should return true. The time stamp comes to the callback only if the message contains timestamps. Example function signature for a replyDetectionCallback would be like
boolean function_name(string message_id, string timestamp [,mixed args]). args is an optional argument.
replayDetectionCallbackData mixed mixed none Any optional values that is needed in callback function can be provided using this option.
storeSCTCallback string string none This is a callback function that should be specified for using secure conversation. This function is called from the WSF/PHP in order to store the {SecurityContextToken/SecureConversationToekn} values. The callback function signature should be as follows.
boolean function_name(string security_token, string global_id,string local_id [,mixed args])

security_token
string will always be available. The gloabl_id or the local_id should be used as the key in storing the security token string. Only one of global_id or local_id or both ids may be available depending on the scenario. args parameter will contain the data specified using the "SCTCallbackData" option.If the persisting of the security  token is successfull, the fuction should return true, false otherwise.
getSCTCallback mixed mixed none This callback function is called from WSF/PHP to obtain the presisted security token string. The callback function signature should be as follows. 
string function(string sct_id, int sct_id_type, bool is_encryption[.mixed args])
sct_id
contains the value that was used as the key in storing the security token string. The second variable specifies whether the provided key is a global id or a local id. If the provided sct_id is a global id, the sct_id_type value will be 2 (constant WS_SCT_ID_GLOBAL) and if the sct_id is local_id then it will be 1 (constant WS_SCT_ID_LOCAL).
However, if security context token (pre-agreed and established offline) is refered, then sct_id might be NULL. Such a situation can be handled by refering to is_encryption value, so that if the pre-agreed sct is different for encryption and signature, then it could be accessed based on is_encryption_value.
deleteSCTCallback mixed mixed none This callback function is called from WSF/PHP to delete persisted security token strings with a given id. The function signature
should be as follows.
boolean function_name(string sct_id, int sct_id_type)
Here the sct_id is key used to store the security context token string and sct_id_type is the id_type of the provided sct_id which can be either global id or local id.
SCTCallbackData mixed mixed none Any optional values that is required with the secure conversation callback functions can be specified using this option.

WSClient and WSService Options for Security

Option Data Type Value Domain Default Value Description
policy WSPolicy WSPolicy instance none Policies to be used when using WS-Security.
securityToken WSSecurityToken WSSecurityToken instance none User specific security parameters to be used when using WS-Security.
useOwnSTS boolean boolean FALSE When this option is set to true, a security enabled service can act as a security token service in addition to providing the service functionality.


Only a common subset of security options can be provided as user options. For more complex scenarios, you should provide the appropriate policy file.


WS-SecurityPolicy File Example

<wsp:Policyxmlns:wsp='http://schemas.xmlsoap.org/ws/2004/09/policy'>
<wsp:ExactlyOne>
<wsp:All>
<sp:AsymmetricBindingxmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'>
<wsp:Policy>
<sp:InitiatorToken>
<wsp:Policy>
<sp:X509Tokensp:IncludeToken='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Always'>
<wsp:Policy>
<sp:WssX509V3Token10/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:InitiatorToken>
<sp:RecipientToken>
<wsp:Policy>
<sp:X509Tokensp:IncludeToken='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Always'>
<wsp:Policy>
<sp:WssX509V3Token10/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:RecipientToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic256Rsa15/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Strict/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
<sp:EncryptBeforeSigning/>
<sp:OnlySignEntireHeadersAndBody/>
</wsp:Policy>
</sp:AsymmetricBinding>
<sp:Wss10xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'>
<wsp:Policy>
<sp:MustSupportRefIssuerSerial/>
</wsp:Policy>
</sp:Wss10>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>