About certificates and Shipium

When connecting to Shipium, part of the trust process is the use of shared Transport Layer Security (TLS) certificates. This document outlines the steps for adding Amazon's Root certificate authorities, which helps prevent the risk of service disruption.

Please note that our certificate provider, Amazon Web Services (AWS), discourages the use of certificate pinning as outlined in this article. However, the solution provided below should prevent most issues if your organization does pin certificates.

Recognize a potential problem

You may need to use the instructions above if you see errors similar to the below (this example is from Java code, but similar errors will appear in other programming languages).

"javax.net.ssI.SSLHandshakeException - 
  PKIX path building failed: 
  sun.security.provider.certpath. 
  SunCertPathBuilderException: unable to find valid certification path to requested target",
  "detailedDescription": 
    "HTTP POST on resource 'https://api.shipium.com:443/api/v1/shipment/carrierselection/label' failed: 
    PKIX path building failed:sun.security.provider.certpath. 
    SunCertPathBuilderException: unable to find valid certification."

Some reformatting was applied to the above example error message for readability.

Solution

The error above is a result of either:

the TLS certificate attached to the resource not being valid; or
the certificate or its root certificate authority not being added to the trust chain from the instance where the client is being run.

In order to solve this issue and prevent service disruption, AWS recommends that you install all 5 root certificate authorities from Amazon’s Trust Repository. This will allow AWS to manage certificate issuance for us and update it accordingly without service disruption if your organization uses certificate pinning. If these root certificate authorities are installed, then all new certificates issued on our behalf will inherit this trust, which should eliminate the potential for any service issues due to pinning.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful: