This section provides an overview of supported elements of WS-Security in WSO2 SOA Enablement Server. Detailed documentation can be found in the relevant Javadocs (in the packages org.systinet.wasp.security.ws and org.systinet.wasp.security.ws.conf). Constants, such as names of algorithms, are stored in the Javadoc of org.systinet.wasp.security.ws.Constants.
A message secured by WS-Security authenticates the client with a UserName security token it contains and by credentials created by the developer in the incoming validator.
WS-Security uses wsu:Id (Id as defined by XML Signature and XML Encryption) identification of message elements. In most cases these elements have wsu:Id set to create dependencies between them. For example, encrypted data are referenced from the Encrypted key. If you want to refer to an arbitrary element of a message, the schema of the message must define wsu:Id. If the message does not provide wsu:Id, you may only refer to the body of the message.
The order in which the components of an element are processed is given by the element's order property. On the sender side, the components are appended to the generated security header from the lowest order value at the end to the highest order at the top. Because components are appended from bottom to top, the highest order component is processed last but it is the first one in security header.
It is reasonable to assign higher order to security tokens, lower to encrypted keys, and the lowest to encrypted data and signatures. By default, an external token's order is higher than the order of other components. On the receiver side, the order is given by the position of the element in the security header.
Security tokens represent different types of claims (for example, user names, keys, certificates, etc.). A security token usually has an XML representation of itself in the message, but sometimes it is not desirable to place it there (for example, when you want to use a symmetric key using a symmetric key token). WSO2 SOA Enablement Server solves this problem by allowing users to mark security tokens as external. An external security token is never placed in a message but, like normal security tokens, it can be referenced from the WS-Security configuration of outgoing messages and it can be referenced in incoming messages. In WSO2 SOA Enablement Server, only security tokens can hold or identify keys used in WS-Security.
WSO2 SOA Enablement Server provides the following types of security tokens:
Username token
This token is defined by the WS-Security specification. It uses either the JAAS configuration entry NamePasswordAN (plain text password) or NameDigestAN (digested password). The token also represents a symmetric key generated by the PSHA1 algorithm.
The Username token represents a claim that a known user is sending the message. This token is usually signed and/or encrypted. The receiver checks the user and its password. If the check is not successful, the processing is stopped and a SOAP fault is returned. For more details, see org.systinet.wasp.security.ws.conf.SecurityTokenConf.
X.509 token
This token is defined by the WS-Security specification. It is a binary security token that uses an X.509 certificate and a corresponding private key for signature and encryption. The sender must know the private key to sign a message and the public key to encrypt a message. The receiver must know the public key to verify a signed message and the private key to decrypt an encrypted message. For more details, see org.systinet.wasp.security.ws.conf.SecurityTokenConf.
Symmetric key token
This security token is WSO2 SOA Enablement Server specific. It represents a symmetric key that is used for signing and encryption. A symmetric key is a key that is agreed upon between sender and receiver. It is never passed in a message: it can be configured as an external security token only. For more details, see org.systinet.wasp.security.ws.conf.SecurityTokenConf.
The KeyInfo element represents the key used in a message. The WS-Security specification prefers the usage of security tokens and defines the extension of KeyInfo to reference security tokens. Thus WSO2 SOA Enablement Server does not offer direct usage of keys: the key must be represented by a security token.
WSO2 SOA Enablement Server provides two SecurityTokenReferences: a reference by wsu:Id and a reference by key identifier. WSO2 SOA Enablement Server also allows tokens to be referenced by KeyInfo's KeyName in this case the KeyName is the wsu:Id of the security token. Usually it is used to reference an external symmetric key security token, when this reference is presented as the name of the key to outside world. For more details, see org.systinet.wasp.security.ws.conf.KeyInfoConf.
A signature enables the receiver to check if a message or part thereof (including elements of WS-Security) was altered during transport. You can select elements to sign by adding references to them. You can also set the body element to be signed (if you cannot set it using a reference). You can set the algorithms of digest, canonicalization, signature, and transform. You can also set KeyInfo to identify the key that will be used for signing.
Encryption in WS Security is specified in the elements EncryptedData, EncryptedKey and ReferenceList.
Encrypted data refers to the part of a message that will be encrypted. You can specify the following:
Which elements in a message will be encrypted, such as body or an element identified by id.
How the element will be encrypted (content only or whole element).
The algorithms used for encryption.
The KeyInfo carrying key. If KeyInfo is not specified, the key is retrieved from the corresponding EncryptedKey. If KeyInfo is specified, the encrypted data must be listed in the WS-Security Reference list.
EncryptedKey element holds the key used for encrypted data. The stored key is encrypted with a specified algorithm. If the stored key is not given then it is generated using a random generator. If KeyInfo is not specified, the key is retrieved from the EncryptedKey to which it belongs. If KeyInfo is specified, the encrypted data must be listed in the Reference list.
The reference list is a list of encrypted keys and encrypted data that are not referenced from an encrypted key.