WS-Security Policy File Elements

This topic explains how SOAP messages are processed by the XML elements in a WS-Security policy file (WSSE file).

Username/Password Token

Username/password tokens serve to authenticate the sender of the SOAP message to the recipient. Note that username/password tokens should always be used in conjunction with either digital signatures or encryption, otherwise a malicious party could intercept the SOAP message and read the username and password.

Requiring Username/Password Tokens on Inbound SOAP Messages

You can specify that incoming SOAP messages must be accompanied by a username/password token. To pass the security gate set up by the WSSE file, the token must match a principle known to the WebLogic Server security provider.

To specify that a username/password token is required for inbound SOAP messages, use the following syntax.

	<wsSecurityIn>
		<token tokenType="username"/>
	</wsSecurityIn>

Enhancing Outbound SOAP Messages with Username/Password Tokens

To specify that outgoing SOAP messages include a username/password token use the following syntax. Note that the <password> element must contain the type attribute and that attribute must have the value TEXT.

    <wsSecurityOut>
        <userNameToken>
            <userName>user1</userName>
            <password type="TEXT">password1</password>
        </userNameToken>
    </wsSecurityOut>

Digital Signature

Digital signatures are used to authenticate the sender of the SOAP message and to ensure the integrity of the SOAP message (i.e., to ensure that the SOAP message is not altered while in transit). When a digital signature is applied to a SOAP message, a unique hash is produced from the message, and this hash is then encrypted with the sender's private key. When the message is received, the recient decrypts the hash using the sender's public key. (Note that the public key is contained in a digital certificate, provided either by a third party or by the sender himself. When the certificate is generated by the sender, the message is called "self-signed".) This serves to authenticate the sender, since only the sender could have encrypted the hash with his private key. It also serves to ensure that the SOAP message has not been tampered with while in transit, since the recipient can compare the hash sent with the message with a hash produced on the recipient's end.

Requiring Digital Signatures on Inbound SOAP Messages

To specify that a digital signature is required for inbound SOAP messages, use the following syntax.

	<wsSecurityIn>
		<signatureRequired>true</signatureRequired>
	</wsSecurityIn>

Enhancing Outbound SOAP Messages with Digital Signatures

To specify that outgoing SOAP messages be signed, use the following syntax.

    <wsSecurityOut>
        <signatureKey>
            <alias>myAlias</alias>
            <password>myKeyStorePassword</password>
        </signatureKey>
    </wsSecurityOut>

    <keyStore>
        <keyStoreLocation>path_to_keystore</keyStoreLocation>
        <keyStorePassword>myKeyStorePassword</keyStorePassword>
    </keyStore>

When signing an outbound message, the <keystore> element must be present so that the digital certificate (containing your public key) and your associated private key can be retrieved from the keystore.

Encryption

Encryption ensures confidential communication between the sender and the recipient. The sender uses the recipient's public key to encrypt the message. Only the recipient's private key can successfully decrypt the message ensuring that it cannot be read by third parties while in transit.

Requiring Digital Signatures on Inbound SOAP Messages

The following <encryptionRequired> element has two purposes. (1) It requires that incoming SOAP message must be encrypted with your public key and (2) it gives decryption instructions for the incoming message.

	<wsSecurityIn>
		<encryptionRequired>
			<decryptionKey>
				<alias>myAlias</alias>
				<password>password_key_store</password>
			</decryptionKey>
		</encryptionRequired>
    </wsSecurityIn>

The <alias> and <password> elements are used to access the keystore where your decrypting private key is stored.

Enhancing Outbound SOAP Messages with Encryption

To encrypt outgoing messages with the intended recipient's public key, use the following syntax.

 	<wsSecurityOut>
		<encryption>
			<encryptionKey>
				<alias>recipient_alias</alias>
			</encryptionKey>
		</encryption>
	</wsSecurityOut>

	<keyStore>
		<keyStoreLocation>path_to_keystore</keyStoreLocation>
		<keyStorePassword>myKeystorePassword</keyStorePassword>
	</keyStore>

Related Topics

Web Service Security