Overview of WS-Security 1.0 with the SOAP API

Upgrading to certificate-based authentication requires your programming library to support WS-Security 1.0. This overview section provides helpful information about which WS-Security elements all merchants must configure in their SOAP integration. If your SOAP integration uses a programming environment that is not available as a toolkit example or a commercial off-the-shelf software (COTS), follow the instructions in this section to remain compliant.

Configurable WS-Security Elements

WS-Security ensures secure SOAP communications between you and Cybersource. These are the WS-Security elements you must support and configure for this upgrade:

Digest algorithm
to verity the integrity of message bodies.

X.509 Binary Security Token (BST)
for authentication.

Security timestamps
to prevent replay attacks.

Digital signature
to ensure message integrity.

Canonicalization
to standardize XML formatting for signing.

For more information about the WS-Security standards, see the OASIS Web Services Security: SOAP Message Security 1.0 (WS-Security 2004)
guide.

Configure WS-Security Algorithms

Find the elements listed in the Security Element column in your payment system and set them to the values in the Required Value column. You must verify that your WS-Security library is configured to use these algorithms. The method for setting these values is dependent on your language library.

Some WS-Security libraries use algorithms by default, while others require you to configure the algorithms. Before setting these values, verify what your library's default values are and configure the necessary values.

WS-Security Algorithms
Security Element	Required Value
Signature Algorithm	http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
Digest Algorithm	http://www.w3.org/2001/04/xmlenc#sha256
Canonicalization Algorithm	http://www.w3.org/10/xml-exc-c14n#
Signature Transformations	http://www.w3.org/2001/10/xml-exc-c14n#

Update Your Authentication Method

You must configure your SOAP payment system to authenticate using the X.509 certificate in your .p12 file as a Binary Security Token (BST). For more information, see the Security Tokens section on page 18 in the OASIS Web Services Security: SOAP Message Security 1.0 (WS-Security 2004)
guide.

Add Security Timestamps

Verify that security timestamps are enabled in your WS-Security configuration. Enabling timestamps is typically sufficient for most payment systems. Timestamps help prevent replay attacks by validating how recent message was sent.

Generate Digital Signatures

Use your private key in your .p12 file to generate digital signatures. Embed the signatures in your SOAP message. For more information about how to message signatures, see the Signing Messages section on page 28 in the OASIS Web Services Security: SOAP Message Security 1.0 (WS-Security 2004)
guide.

Extract Keys from .p12 File

Run these commands to the extract your private key and public certificate from your .p12 file:

openssl pkcs12 -in <Merchant_ID>.p12 -nocerts -out <Merchant_ID>.key

openssl pkcs12 -in <Merchant_ID>.p12 -clcerts -nokeys -out  <Merchant_ID>.crt

To create your p12 certificate, see Create a .p12 File.

Remove Username and Password Authentication

Search your application for any code or configuration related to your merchant credentials and remove it. Your WS-Security library should now automatically add your binary security token instead.

If your integration contains multiple merchants that require you to complete this transition over a period of time, Cybersource will support both authentication methods until the deadline.