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. DOM node representing the corresponding policy.

  3. 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" "EncryptBeforeSigning" 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.

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 User's certificate to be used for signing, loaded from the function get_cert_from_file()
passwordType string "PlainText" |"Digest" Digest Password type used in UsernameToken
password string string none User's password used for UsernameToken
privateKey string string none User's private key, loaded from the function get_key_from_file()
receiverCertificate string string 
none Receiver's certificate to be used for encryption, loaded from the function get_cert_from_file()
ttl
int
int
360 The time period within which the message would be valid in seconds
password_callback string string none Name of the password callback function, which is a user defined function that accepts a username and returns the corresponding password.

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.


 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:Policy xmlns:wsp='http://schemas.xmlsoap.org/ws/2004/09/policy'>
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:AsymmetricBinding xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'>
        <wsp:Policy>
          <sp:InitiatorToken>
            <wsp:Policy>
              <sp:X509Token sp: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:X509Token sp: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:Wss10 xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'>
        <wsp:Policy>
          <sp:MustSupportRefIssuerSerial />
        </wsp:Policy>
      </sp:Wss10>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>