Print this page

HTTPS Security Certificate Change from SHA-1 to SHA-256 hash algorithms

Knowledge Article Number 000206493
Description

What is changing?

To maintain alignment with security best practices and the industry-wide shift to use more complex algorithms for HTTPS certificates, Salesforce will be replacing the current HTTPS certificates, which are signed with the SHA-1 hash algorithm, with new certificates signed with the SHA-256 hash algorithm. Additionally, Salesforce will be consolidating our trusted third-party certificate authorities (CA) to leverage only Symantec-issued certificates.

 

HTTPS certificates are reflected in the browser’s URL bar to indicate a secure connection while accessing secure websites, including Salesforce.

 

What action do customers need to take?

In order for users to continue to have access to Salesforce, customers need to ensure their Operating Systems, browsers, and middleware are capable of accepting HTTPS certificates with the SHA-256 hash algorithm.

 

Ensure that the list of trusted certificate authority (CA) certificates in your software includes the newer, self-signed, root version of the "VeriSign Class 3 Public Primary Certification Authority - G5" certificate. This certificate can be downloaded from Symantec here. Up-to-date software since approximately 2010 typically trusts this certificate already. Older software might not already trust this newer Verisign root certificate.

 

What will happen if my operating systems, browsers, middleware, and integrations are not capable of accepting these new HTTPS certificates?

If your operating systems, browsers, middleware, and integrations cannot validate the new HTTPS certificates, those operating systems, browsers, middleware, and integrations will not be able to access Salesforce. Users operating on those operating systems, browsers, middleware, and integrations will also not be able to access Salesforce.

 

When will the new certificates be implemented?

Salesforce plans to implement the new certificates in Sandbox and Production instances according to the following phased schedule:

 

Sandbox Instances

Certificate Change Targeted Date

CS1, CS2, CS3, CS4, CS12, CS13, CS30

April 13, 2015

CS5 & CS6

May 19, 2015

CS7, CS8, CS9, CS10, CS11, CS14

May 18, 2015

CS15, CS16, CS17, CS18, CS20

May 20, 2015

CS21, CS22, CS23, CS24, CS25, CS26

May 18, 2015

CS32, CS33

May 19, 2015

CS80, CS81

May 19, 2015

 

Production Instances

Certificate Change Targeted Date and Time

NA0, NA1, NA3

August 5, 2015, 19:00 - 20:00 PDT

AP0, AP1, AP2

August 6, 2015, 10:00 - 11:00 PDT

NA2, NA7, NA10, NA11, NA14, NA15

August 12, 2015, 03:00 - 04:00 PDT

NA4, NA8, NA9, NA12, NA13, NA16, EU0, EU2, EU3

August 12, 2015, 19:00 - 20:30 PDT

NA17, NA18, NA22, NA23, NA24, NA27, NA41

August 13, 2015, 03:00 - 04:00 PDT

EU1, EU4, EU5

August 13, 2015, 17:00 - 18:00 PDT

NA5, NA6, NA19, NA20, NA25, NA26, NA29

August 13, 2015, 19:00 - 20:30 PDT

NA21

August 19, 2015, 19:00 - 20:30 PDT

login.salesforce.com (TYO DC covering APAC instances)

August 26, 2015, 10:00 - 11:00 PDT

login.salesforce.com (all but TYO DC)

August 26, 2015, 19:00 - 20:00 PDT

 

If you do not know what instance you are on, access the “What instance am I using” Knowledge article.

If you locally cache certificates, please join the Certificates Changes Community Group to obtain the required certificates and get notified about the exact certificate update times on these dates.

 

Is there a way to test if I am prepared for this change?

Yes. We have established this test page to quickly check if your operating systems, browsers, middleware, and integrations accept HTTPS certificates with the SHA-256 hash algorithm. Instructions covering how to use this test page are farther below in the “How can I leverage the Test Site to check compatibility in my environment” section of this Knowledge article.

 

Additionally, if you have a sandbox available, we strongly recommend that you test your operating systems, browsers, middleware, and integrations using your sandbox. Sandbox certificates were updated earlier this year.

 

Why is Salesforce not changing the HTTPS certificates sooner?

The HTTPS certificates that Salesforce uses today are secure. However, it is a best practice to continuously increase the complexity of security encryption protocols and tools. We designed the timeline to give customers time to prepare for this change while maintaining a secure environment.

 

How will the consolidation of trusted third party certificate authorities by Salesforce affect me?

Moving forward, Salesforce will use certificates issued by Symantec. Salesforce's older certificates used multiple vendors. The new certificates chain up to the same "VeriSign Class 3 Public Primary Certification Authority - G5" root certificate instead of chaining up to more than one root certificate. The test site uses a certificate issued by Symantec.

 

What if we use middleware that requires us to upload the certificate into the middleware (i.e. locally cached)?

If your organization is running middleware that requires the server and/or intermediate certificates to be locally cached, you will need to update the cached certificates as a result of this change. This is not typical in most software, but some API middleware systems do have this requirement. To learn more about this how this information will be communicated, please join the customer Success Community group, Official: Certificate Changes.

 

Which Operating Systems and browsers are compatible with SHA-256?  

The table below outlines the minimum requirements for certificates with the SHA-256 hash algorithm. If your Operating Systems (OSs) and browsers meet or exceed the minimum requirements, they will be able to access and validate certificates with the SHA-256 hash algorithm.

 

Minimum version requirements for Operating Systems (OS)

 

Minimum OS Version

(SSL Certificates)

When was the minimum version released?

Apple OS X

10.5+

October 26, 2007

Apple iOS

3.0+

June 17, 2009

Android

2.3+

December 6, 2010

Blackberry

5.0+

August 4, 2009

ChromeOS

N/A

No minimum requirement

Windows

XP SP3,

Vista+

April 21, 2008

Windows Phone

7+

NA

Windows Server

2003 SP2 +Hotfixes,

2008+

March 13, 2007

 

Minimum version requirements for Salesforce Supported Browsers

 

Minimum Browser Version

When was the minimum version released?

Chrome

26+

March 26, 2013

April 4, 2013 (Android)

April 9, 2013 (iOS)

Firefox

3.0+

June 17, 2008

Internet Explorer

6+

August 27, 2001

Safari

3+

June 11, 2007

 

How can I leverage the Test Site to check compatibility in my environment?

For browsers:

  1. Visit this page: https://sha2test.force.com

  2. If the following appears on your screen, your Operating System and browser is compatible with certificates with the SHA-256 hash algorithm:

  1. If you do not see the a green page with the text: “SHA-256 Compatibility Test Passed,” then your Operating System and/or browser are not compatible with certificates with the SHA-256 hash algorithm.

 

For Middleware/Integrations

To test the compatibility of an API client that uses SOAP to communicate with Salesforce:

  1. Set up an API client in a test environment.

  2. In that test environment, change the API client's login endpoint hostname from login.salesforce.com or [MyDomain].my.salesforce.com to https://sha2test.force.com.

    1. As an example, change https://login.salesforce.com/services/Soap/u/32.0 to https://sha2test.force.com/services/Soap/u/32.0 while leaving the path as-is.

  3. Log in with that API client.

  4. If you see an error message that resembles the following: "INVALID_LOGIN: Invalid username, password, security token; or user locked out." or “Content is not allowed in prolog.”, then this test passed and your integration can validate certificates with the SHA-256 hash algorithm.

    1. The presence of this response means that the underlying TLS connection was successful, despite the higher-level error. The TLS connection is the focus of this test.

  5. If you instead see an error message that involves TLS or HTTPS, then the test has failed. Your API client will require adjustments or upgrades to operate properly with Salesforce, when Salesforce switches to the new certificates.

 

To test the compatibility of an API client that uses REST to communicate with Salesforce:

  1. Set up an API client in a test environment.

  2. In that test environment, change the API client's access token retrieval endpoint hostname from login.salesforce.com or [MyDomain].my.salesforce.com to sha2test.force.com.

    1. As an example, change https://na1.salesforce.com/services/oauth2/token to https://sha2test.force.com/services/oauth2/token while leaving the path as-is.

Alternatively, it's possible to change the API client's service URL from [instance].salesforce.com or [MyDomain].my.salesforce.com to sha2test.force.com.

  1. As an example, change https://na1.salesforce.com/services/data/v32.0/ to https://sha2test.force.com/services/data/v32.0 while leaving the path as-is.

  1. If you see an OAuth error, an "INVALID_SESSION_ID Authorization required" error, or a "400 Bad Request" error, then this test passed.

    1. The presence of this response means that the underlying TLS connection was successful, despite the higher-level error. The TLS connection is the focus of this test.

  2. If you instead see an error message that involves TLS or https, then the test has failed. Your API client will require adjustments or upgrades to operate properly with Salesforce, when Salesforce switches to the new certificates.

 

What is the impact of this change to users using certificate authority (CA) signed certificates for webservice callouts & SSO users?

Apex callouts, delegated authentication, and workflow outbound messaging should not be affected by Salesforce's change to the [instance].salesforce.com (e.g. na7.salesforce.com), [instance].force.com, [mydomain].my.salesforce.com, login.salesforce.com, test.salesforce.com, and www.salesforce.com certificates. Salesforce itself is already compatible with SHA-256 signed certificates, which means that calling out to another Salesforce organization or to an endpoint that uses a SHA-256 signed certificate is supported.

 

The proxy.salesforce.com certificate is not included in this switchover to SHA-256, but it might be updated to SHA-256 before its October 2017 expiration date. Advance notice will be given if that happens via the Certificates Changes Community Group.

 

Some SAML configurations use Salesforce's proxy.salesforce.com certificate, and that certificate is not being changed by Salesforce at this time. Customers are free to use their own certificate for SAML assertions, and those can be signed with SHA-256 if it's signed by a certificate authority (including one's own certificate authority). It is recommended to use a certificate that is specific to your organization for SAML.

 

What do I need to do to make Apex Data Loader, versions 13 through 23, compatible with Salesforce's SHA-256 signed certificates?

Salesforce generally recommends using the newest version of the Apex Data Loader. If that is not possible in your integration, then it is possible to make versions 13 through 23 work by following these steps:

 
  1. Download the certificate here and save it into "C:\Program Files\salesforce.com\Apex Data Loader [your version # here].0\_jvm\bin".

  2. Uncheck the “Read Only” bit in the Properties dialog of "C:\Program Files\salesforce.com\Apex Data Loader [your version # here].0\_jvm\lib\security\cacerts".

  3. Open a Command Prompt window

  4. Within the "C:\Program Files\salesforce.com\Apex Data Loader [your version # here].0\_jvm\bin" folder in a Command Prompt window, run: keytool -import -keystore ..\lib\security\cacerts -file "VeriSign-Class 3-Public-Primary-Certification-Authority-G5.pem" -alias vsignc3g5 -storepass changeit

 

What are the minimum requirements for the Java Virtual Machine?

Different versions of Java have their own requirements. Check the version of Java that you are running with the java -version command within Java's bin folder and follow the advice below for your particular Java version:

 

Earlier than 1.4.2

  • Not supported. Please upgrade to a newer version.

 

1.4.2 to 1.4.2_19

  • Import the new "VeriSign Class 3 Public Primary Certification Authority - G5" root certificate into the lib/security/cacerts file using Java's keytool command within Java's bin folder after downloading the root certificate into that folder: keytool -import -keystore ../lib/security/cacerts -file "VeriSign-Class 3-Public-Primary-Certification-Authority-G5.pem" -alias vsignc3g5 -storepass changeit

  • BouncyCastle's bcprov-jdk14-152.jar file must exist in the Java command line's classpath

  • BouncyCastle must be enabled in Java's java.security file, which is typically through adding security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider to the lib/security/java.security text file.

 

1.5.0 to 1.6.0_18

  • Import the new "VeriSign Class 3 Public Primary Certification Authority - G5" root certificate into the lib/security/cacerts file using Java's keytool command within Java's bin folder after downloading the root certificate into that folder: keytool -import -keystore ../lib/security/cacerts -file "VeriSign-Class 3-Public-Primary-Certification-Authority-G5.pem" -alias vsignc3g5 -storepass changeit

 

1.6.0_19 and higher

  • No changes are needed.

 

Sample Errors from Common Middleware Applications

Weblogic 10.3.3 and SHA-256

Customers that use Oracle Weblogic 10.3.3 may encounter an inability to call out successfully to Salesforce when the callout target has a SHA-256 signed server certificate. The following error might appear:

 

General runtime error: FATAL Alert:BAD_CERTIFICATE - A corrupt or unuseable certificate was received

 

To remedy this, Java secure sockets extension (JSSE) must be enabled in Oracle Weblogic.

 

If an older version of the JDK is used, such as JDK 1.6.0_20, then enabling JSSE might result in an error that resembles the following:

 

General runtime error: Cannot get fd for sock=Socket[addr=our.proxy.server/xx.xxx.xxx.xxx,port=8080,localport=56174]:

 

If you encounter that or a similar error while using JSSE in Oracle Weblogic, then upgrading Java to 1.6.0_45 or newer should help make the connection work properly.

 

References:

http://docs.oracle.com/cd/E28280_01/web.1111/e13707/ssl.htm#SECMG387

http://w3facility.org/question/osb-bea-000409-cannot-get-fd-for-socksocketaddrour-proxy-serverxx-xxx-xxx-xxxport8080localport59719/

 




Attachments
Name Type Size
PROD_256.zip
70KB

promote demote