ravelinjs JavaScript Library


ravelinjs will be served onto your customers’ browsers, and if you are using client-side encryption, it will operate on your customers’ card details. Therefore, it is our joint responsibility, to ensure we are all diligent in securing and protecting this library from tampering or abuse.

Serving ravelinjs

Our recommendation for securely serving ravelinjs is to include the file as part of your site’s build/bundle process, ensuring the contents are available locally on your hosting server, alongside the rest of your site content, ideally version controlled alongside your site’s code as well.

We do not recommend hosting a copy of ravelinjs from a third-party CDN, for a compromised CDN will allow an adversary to manipulate the content of any files served from there, giving the attacker the ability to execute arbitrary Javascript on your customers’ browser. The .js file containing the ravelinjs code, whether served from your own servers or a CDN, or included in a larger bundle, must be included using a sub-resource integrity digest. Please refer to the MDN documentation available here. In addition, we recommend enforcing a strict Content Security Policy for your site, especially for pages in which payment details are requested.

Here is our recommendation for securely integrating ravelinjs into your site:

  1. Review the code available at Github, ensuring you are aware of the behaviour and contents within.
  2. Download the minified JS from our Github releases.
  3. Compare the SRI digests for this downloaded file against the values provided by Ravelin.
  4. Commit that file to your VCS and employ strict change management around it.
  5. Serve the resulting JavaScript file only over HTTPS, either included inside your site’s bundle or as a standalone script.
  6. Include into an HTML page using a script tag with an integrity attribute.

Using your Public RSA Key

When Ravelin generates your public RSA key, we do so with the understanding that:

  • this key will only be used to encrypt cardholder information via our official SDKs
  • the ciphertexts produced by this operation will be sent to Ravelin only from your server, via HTTPS, using your private Ravelin API token
  • the ciphertexts produced by this operation will not be shared with any third-parties
  • the ciphertext produced by this operation will not be stored on your servers under any circumstances

Ensuring the above steps are taken helps protect the integrity of this key and the data it encrypts. Ravelin are able to rotate your RSA key pairs either at your request, after a cryptoperiod of 3 years, or if we determine any of the above steps to not have been followed. Key rotations are performed by Ravelin, but will require a client-side update to replace the old public key with the new.

Security Audits

As part of our yearly PCI compliance audit, we audit the contents of our ravelinjs library to ensure the code contained with in is secure and that the cryptographic implementations are correct. We’ve open-sourced the library to ensure the code is visible to all interested parties. If you wish to see any of our PCI compliance certificates or have specific questions regarding the security of ravelinjs, please contact us at support@ravelin.com.