U p d a t e - REST API : Http Signature Authentication – Critical Security Update - RELAXED!

[rajvpate]

What Is It?

This is an announcement to provide information about action required from the customers using Cybersource REST APIs. All Cybersource API calls using HTTP Signature Authentication will adhere to industry standards and will allow BOTH WITH AND WITHOUT PARENTHESIS for the http authentication for REST APIs and no longer support the use of parenthesis in the API header after Nov 1, 2023  Jan 22, 2024 Mar 22, 2024 April 22 2024

Audience

Any merchant that uses HTTP Signature Authentication to connect to Cybersource REST APIs.

Details

This update is for http signature authentication scheme supported for Cybersource REST APIs, where the API request headers have an attribute called Signature that contains request-target parameter that is provided in parenthesis like : (request-target), that should be rather sent without the parenthesis like : request-target. There will be a migration period until Nov 1, 2023  Jan 22, 2024 Mar 22, 2024 April 22 2024 where Cybersource API calls will accept both formats of headers - with and without parenthesis.

It is a simple integration change, however it stands very important from industry security standards. Hence, any API requests received after Nov 1, 2023 Jan 22, 2024 Mar 22, 2024 April 22 2024 using parenthesis for request-target in the Signature header for HTTP Signature Authentication will fail.

Old & supported: Here is an example of a request header signature with parenthesis: 

• Signature:"keyid=”123abcki-key1-key2-key3-keyid1234567”, algorithm=”HmacSHA256”, headers=”host (request-target) digest v-c-merchant-id”, signature=”123456iFZ0ZhOHzhejvuAa123456Xv1xykNAEq71234=”” 

New & supported: Here is an example of an updated request header signature with parenthesis removed: 

• Signature:"keyid="123abcki-key1-key2-key3-keyid1234567", algorithm="HmacSHA256", headers="host request-target digest v-c-merchant-id", signature="hrptKYTtn/VfwAdUqkrQ0HT7jqAbagAbFC6nRGXrNzE=”” 

In addition, if the optional header “request-target” is passed and when it is used to calculate the signature and will allow BOTH WITH AND WITHOUT PARENTHESIS for the http authentication for REST APIs , it must be changed from “(request-target)” to “request-target” to avoid service interruptions.  

If you have any questions on this update, please contact customer support : Cybersource Support Center

What Do I Have To Do?

The fix has been implemented internally and no action is required from the consumers of Cybersource REST APIs

If you are a merchant of Cybersource and you use http signature authentication, then update your http signature authentication implementation to remove parenthesis for the request-target in the Signature header before Nov 1, 2023 Jan 22, 2024 Mar 22, 2024 April 22 2024. If you use SDK for your integration, upgrade to the latest SDK that will be released with the fix for this finding in the last week of September – you can watch SDK release updates here: https://developer.cybersource.com/hello-world/release-notes.html. The associated documentation, API Reference and SDK updates shall be published with these fixes in last week of September.

[rajvpate]

The updates to 7 SDKs have been released and they can be found as below:

PLEASE NOTE: Any version of the SDK per below and newer/higher/future versions will have the fix

https://github.com/CyberSource/cybersource-rest-client-node/releases/tag/0.0.50

https://github.com/CyberSource/cybersource-rest-client-dotnetstandard/releases/tag/0.0.1.27

https://github.com/CyberSource/cybersource-rest-client-dotnet/releases/tag/0.0.1.35

https://github.com/CyberSource/cybersource-rest-client-java/releases/tag/cybersource-rest-client-jav...

https://github.com/CyberSource/cybersource-rest-client-python/releases/tag/0.0.48

https://github.com/CyberSource/cybersource-rest-client-ruby/releases/tag/0.0.55

https://github.com/CyberSource/cybersource-rest-client-php/releases/tag/0.0.44

[Leenes Rapheal]

Hello Team
Hope this email finds you well!

Looking for some clarification around the Cybersource Upcoming Mandates notification sent to merchants. We (paydock) are a Payment orchestration platform provider to merchants and looking for some clarification around below notification received from CyberSource.

Referring below notification received from CyberSource, Pls confirm below:

* Do merchants need to regenerate API keys if they are using their pts/v2/... and tms/v2/... API endpoints ?

Below Comms are  Received from cybersourse:

"Dear Valued Customer,

The security of our clients' information is top priority, and with this in mind we are enhancing our REST and Simple Order API security requirements.

Below is a listing of three security requirements which are mandated for completion starting January 22nd, 2024.

Please ensure your systems are up to date to comply with each requirement.

Failure to be ready for each of these changes could cause a service interruption for your business.

· REST API Digest Parentheses Removal (REST HTTP Signature) - Cybersource API calls using HTTP Signature authentication must adhere to industry standards and will no longer support the use of parentheses within the HTTP header. Production Implement by Date: January 22nd, 2024.

· Default Password p12 Keys (Simple Order API, REST JWT, Batch Upload, Account Updater Batch Upload) - All Cybersource issued P12 keys created after the implementation date will be secured with a password set by the user during key generation within the Cybersource Business Center. This password will not be stored within Cybersource systems and must be securely stored by the user to open the key file and/or for use with your API implementation. Production Implement by Date: February 28th, 2024

· SHA 256 Envelope p12 Keys (Simple Order API, REST JWT) - P12 keys will be generated with an enhanced HmacPBESHA-256 algorithm. This may cause older SDK's and/or Operating Systems to not be able to access the key. Production Implement by Date: February 28th, 2024.

For more information, please visit our Knowledge Base article with updated details and dates as we move closer.

Please do not hesitate to contact the Cybersource support team if you have any questions or concerns. Cybersource Support Center"

Await for your clarification. 

Thanks 

[rajvpate]

Thank you for reaching out. Regarding your question :

• Referring below notification received from CyberSource, Pls confirm below:
• * Do merchants need to regenerate API keys if they are using their pts/v2/... and tms/v2/... API endpoints ?

If the existing keys you use are NOT expired, you may continue to use them. Only when you generate new keys after Feb 2024, it will require a strong password and SHA256.

Please reach out to https://support.cybersource.com/ for more assistance.

[Scott Hillman]

Is the updated version of the AuthenticationSdk in Maven version "0.0.28"?
 See pom.xml below
<!-- https://mvnrepository.com/artifact/com.cybersource/AuthenticationSdk -->
<dependency>
<groupId>com.cybersource</groupId>
<artifactId>AuthenticationSdk</artifactId>
<version>0.0.28</version>
</dependency>

[Scott Hillman]

Actually, in re-reading the knowledge base doc I see that it is referring to the cybersource-rest-client-java having updates not the AuthenticationSdk. So similar question to above.

Is the updated version of the cybersource-rest-client-java in Maven version "0.0.57"?
 See pom.xml below
<!-- https://mvnrepository.com/artifact/com.cybersource/cybersource-rest-client-java -->
<dependency>
<groupId>com.cybersource</groupId>
<artifactId>cybersource-rest-client-java</artifactId>
<version>0.0.57</version>
</dependency>

[RandyK]

Hi,

Is this mandate in test system already? Will it be rolled out to test before Production ? thank you,Randy

[rajvpate]

Until Jan 22, 2024, the platform will accept both formats: with and without parenthesis. i.e. (request-target) as well as request-target will be accepted. Hope this helps.

[rajvpate]

@Scott Hillman : All you need to do is consume the latest client sdk : If using Java: https://github.com/CyberSource/cybersource-rest-client-java/releases/tag/cybersource-rest-client-jav...

The authentication updates are included in the package for each client SDK, as applicable. Hope this helps. Please reach out  to https://support.cybersource.com/ for more assistance.

[Navaneetha Battu]

Hello Team, we are using Simple Order API Client similar to Using SOAP (cybersource.com) document, do we need to make any changes and also is it possible to test our integration in test environment prior?

[rajvpate]

@Navaneena : Only REST APIs are impacted by this change.

[Michele Leoni]

Hello Team,

we are usind this java sdk:

<dependency>
 <groupId>com.cybersource</groupId>
 <artifactId>cybersource-sdk-java</artifactId>
 <version>6.2.13</version>
</dependency>

Do we need to upgrade it?

Thanks in advance

Michele

[rajvpate]

@Michele : The SDK you listed is for the Simple Order API SDK, so you should not need an upgrade. 

If you consume REST API SDKs, then upgrade is required.

[Bill Chosiad]

Cybersource has stated above, "Until Jan 22, 2024, the platform will accept both formats: with and without parenthesis,"  implying that after January 22, the old format will no longer be accepted *IN PRODUCTION*. 

On what date may we expect the old format to stop working in the *NON-PRODUCTION* testing environment?  Only at that point can we do a valid test to see if our changes are actually working.  If we find our changes do not work in the non-prod environment, we'll need some additional time to rework and retest them.

Surely you realize the importance of having the non-prod environment reflect the anticipated production environment *before* (preferably months before) you make the change to production. You seem to be avoiding this question, as it was asked above by both Navaneetha Battu and RandyK and was left unanswered in both cases. That is, unless I've misunderstood, and by "the platform" you mean both production and non-production testing environments

If you don't currently have an answer, when do you expect to have made a decision regarding the non-production testing environment? Is there something standing in the way of making such a decision? Or are you telling us that the non-production changes will be rolling out the same day as the production changes?

[Jonathan Zhang]

Hi,

Our integration is built on these two SDKs, do we need to upgrade anything? Thank you!

<dependency>

<groupId>cybersource</groupId>

<artifactId>cybsclients</artifactId>

<version>1.5.0</version>

<scope>system</scope>

</dependency>

<dependency>

<groupId>cybersource</groupId>

<artifactId>cybssecurity</artifactId>

<version>1.5.0</version>

<scope>system</scope>

</dependency>

[JC]

I agree with Billy.

Please provide a response to him.

[Jon B]

@rajvpate Hello, we are using the CyberSource module 3.5.6 for Adobe Commerce Cloud 2.4.2.  It is configured to use the SOAP Toolkit API as our Payment API and Flex Microform as the Checkout Flow Type.  Does this requirement for January 22, 2024 affect us at all?  Thanks.

[Jon B]

Sorry, in the above question, we are currently using CyberSource module 3.5.4 (not 3.5.6 ) for Adobe Commerce Cloud 2.4.2.  Will we be OK on January 22, 2024?

[Nalini]

Hello, 

We are using  cybersource  Simple Order API- Decision Manager check SOAP service in our application. We got the email from Cybersource. Do we need to upgrade SOAP APIs also? Please confirm 

[Michele Leoni]

Hello Team,

about "SHA 256 Envelope p12 Keys (Simple Order API, REST JWT) - P12 keys will be generated with an enhanced HmacPBESHA-256 algorithm. This may cause older SDK's and/or Operating Systems to not be able to access the key. Production Implement by Date: February 28th, 2024."

Our JDK supports these chiper algoritms:

- PBEWithHmacSHA256AndAES_128
- PBEWithHmacSHA256AndAES_256

So does my environment support the new algorithm? I'm not sure about the end part AES_128/256 that is not specified here: HmacPBESHA-256.

Thanks in advance

Michele

[rajvpate]

@Navaneetha Battu : Apologies for late response, however, for Simple Order APIs, you do not need to make updates. Hope this helps.

[rajvpate]

@Bill Chosiad : The non production & production environment both shall exhibit the same behavior. If the requests you send without parenthesis in the non-production environment behaves as expected, you should be good. 

[rajvpate]

@Jon B : You should be fine with the SDK you use and you do not need to make any changes.

[rajvpate]

@Nalini: Upgrade for SOAP API is not required with respect to the request-target changes described in the blog post.

[Bill Chosiad]

@rajvpatestated: The non production & production environment both shall exhibit the same behavior. If the requests you send without parenthesis in the non-production environment behaves as expected, you should be good.

Imagine this: Our code contains 3 places where we call Cybersource. We fix two of those places, but mistakenly miss the 3rd.  Our code will continue to work in both PROD and NON-PROD until you make the change.  At that point, it will fail in both places and we will be left scrambling to push a fix into production in a rush.

We wish to avoid that.  Given the scenario above, please explain how we be sure things would work before you make the production cut-over. 

[Rupa]

Hi,

We are using the below two dependencies,

<dependency>
<groupId>cybslib</groupId>
<artifactId>cybsclients</artifactId>
<version>1.5</version>
<scope>compile</scope>
</dependency>

<dependency>
<groupId>cybslib</groupId>
<artifactId>cybssecurity</artifactId>
<version>1.0</version>
<scope>compile</scope>
</dependency>

Do we need to do any changes on SDK upgrade or for p12 key change? Pls assist.

[rajvpate]

If you use Flex APIs and plan to upgrade to the SDK, here are a few helpful resources:

The relevant lines of code they’re looking for specifically for instantiating an API client:

• Creating the generic API client using the MerchantConfig class
• Creating a Microform API client using the generic client we just created
• Generating the capture context with the Microform API client

• MicroformIntegrationApi – Domain-specific API client

A Java application has been added, which shows the integration path.

Developer Guide : https://developer.cybersource.com/docs/cybs/en-us/digital-accept-flex/developer/all/rest/digital-acc...

[bilalmirza]

Hello,

Has this been implemented in the test system already? Will it undergo testing before being rolled out to production? Thank you Bilal.

[Arun Kamaraj]

Hi.,

Is there any instruction set to check if Cybersource SDK is used?

If Simple Order APIs are only used,  then still do Cybersource SDK version upgrade needed?

Regards,

Arun Kamaraj

[realAbhis1901]

Hi Team,

if I update from cybersource-rest-client-dotnet-0.0.1.25 to cybersource-rest-client-dotnet-0.0.1.29 will it helpful to solve the latest SDK update mandate as per the new guidelines of CyberSource?

[eulergroupie]

The date in this blog is Mar 22, 2024, but the Cybersource article still shows Jan 22, 2024. Can you please confirm production date?

[eulergroupie]

If we use the Salesforce Commerce Cloud (SFCC), what changes are required in the old cartridge due to the parenthesis issue? If we upgrade to the new Cybersource cartridge, are there any modifications needed or will the new cartridge satisfy the requirements?

Also, is there any specific documentation for SFCC that addresses the password for p12 keys?

[Katie Sheppard]

Hello,

My team received an email containing the following statement "Cybersource will no longer accept parentheses in p12 files to adhere to industry standards"

From my understanding the (request-target) vs. request-target change has no relation to the .p12 files, can you confirm? I want to make sure that as long as we are not using (request-target) in the signature of our REST api calls we shouldn't see any issues.

Thank you

[rajvpate]

@bilalmirza : The test environment endpoint https://apitest.cybersource.com should be able to accept request-target WITHOUT the parenthesis as well as WITH parenthesis (request-target).

This has been done to provide migration time for our clients. If you are able to get successful response from https://apitest.cybersource.com by sending request-target WITHOUT parenthesis, you should be good.

[Kamna Madhwani]

Hello Team,

As stated earlier, any SDK version from the provided link and newer versions will include the fix: like cybersource-rest-client-php version 0.0.44

However, our application is built on PHP 7.4, and we are considering using the cybersource-rest-client-php version 0.0.40. Can you confirm if this version includes all the necessary fixes?

[avenue17]

It is possible to speak infinitely on this question.

[novopet]

You are mistaken. I can defend the position. Write to me in PM.

[chenglm]

Hello,

Good day to you! 

Could you provide the latest production implementation date for the items below? Thank you.

1. REST API Digest Parentheses Removal (REST HTTP Signature) - Cybersource API calls using HTTP Signature authentication must adhere to industry standards and will no longer support the use of parentheses within the HTTP header. Latest Production Implement by Date: ____
   
   
2. Default Password p12 Keys (Simple Order API, REST JWT, Batch Upload, Account Updater Batch Upload) - All Cybersource issued P12 keys created after the implementation date will be secured with a password set by the user during key generation within the Cybersource Business Center. This password will not be stored within Cybersource systems and must be securely stored by the user to open the key file and/or for use with your API implementation. Latest Production Implement by Date: ____
   
   
3. SHA 256 Envelope p12 Keys (Simple Order API, REST JWT) - P12 keys will be generated with an enhanced HmacPBESHA-256 algorithm. This may cause older SDK's and/or Operating Systems to not be able to access the key. Latest Production Implement by Date: ____

[rsmith24]

I realise from the above comments that this seems to be falling on deaf ears, but I would also like to raise my concerns about the test environment. It makes perfect sense for production to run in this cut-over mode, where the headers both with and without brackets are accepted - it allows us to patch systems and implement on our own schedule. It does not however make sense for this to be the case for the test environment. IMHO that should already reflect the state that production will be in once the cut-over has expired, so that we can reliably test our code in advance and not have any unpleasant surprises on the day.

If I were a new implementer, I'd be following the current docs which don't have the brackets in the header, so I'd be fine. If I were testing an existing system and somehow wasn't aware a change was coming, or was part-way through an implementation, it'd be beneficial for my testing to fail immediately, leading to an investigation and hopefully a realisation that changes were afoot. Finally, as someone aware of the change and about to embark on their necessary changes (or indeed having recently completed them), I'd appreciate knowing not only when my changes were successful, but that I'd not inadvertently missed anything.

In summary as far as I can tell there is no value in having the public test environment accept the bracketed header, other than internal benefit for Barclaycard so that they can continue to evaluate pre-production changes, but I'd like to think they have an isolated non-public system for that anyway.

[Pierre Mailhot]

We received an email on Feb 14, 2024 that stated

As previously announced, Cybersource no longer supports REST API requests using HTTP signature authentication to parentheses in the Authentication Payload used by REST integrations to adhere to industry standards.  Cybersource began this change on November 1, 2023, but will continue to support signatures containing parentheses until Mar 22, 2024.

This articles mentions Apr 22, 2024.

Which is right?

[rajvpate]

Thank you for reaching out. This article should be referred to, for latest updates on the timelines. April 22, 2024 is the new timeline for the upgrade.

[rajvpate]

@Kamna Madhwani : The SDK version for PHP 0.0.44 and beyond includes the fix. Lower versions do not have the fix for request-target

[chenglm]

hi Admin, does 22 April 2024 timeline apply to all 3 items in this enhancement? or only apply to item 1 (REST API Digest Parentheses Removal (REST HTTP Signature)?

Thank you.

[chenglm]

Hi Admin @rajvpate ,

Based on latest update, do we still need to make any changes on the 3 items mentioned previously?

1. To remove REST API Digest Parentheses
2. To secure all Cybersource-issued P12 keys with a user-created password
3. To generate P12 keys with an enhanced HmacPBESHA-256 algorithm 

Thank you.