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)); |
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. |
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.
<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>