microsoft/MSR-JavaScript-Crypto

microsoft/MSR-JavaScript-Crypto

Description: Microsoft JavaScript Cryptography Library

Language: JavaScript

License: NOASSERTION

Stars: 67

Forks: 30

Open issues: 5

Created: 2019-07-24T18:19:46Z

Pushed: 2026-06-26T04:53:17Z

Default branch: master

Fork: no

Archived: no

README:

Overview

The Microsoft Research JavaScript Cryptography Library (msrCrypto) has been developed for use with cloud services in an HTML5 compliant and forward-looking manner. The algorithms are exposed via the W3C Web Cryptography API.

The library currently supports RSA encryption (OAEP) and digital signature (PSS); AES-CBC and GCM encrypt/decrypt; SHA-256/384/512, HMAC with supported hash functions; PRNG (AES-CTR based) as specified by NIST; ECDH; ECDSA; and KDF (Concat). The library is tested on IE8, 9, 10, 11, Microsoft Edge and latest Firefox, Chrome, Opera, and Safari browsers.

This library includes big-number integer arithmetic to support the aforementioned cryptographic algorithms. It supports unsigned big integer arithmetic with addition, subtraction, multiplication, division, reduction, inversion, GCD, extended Euclidean algorithm (EEA), Montgomery multiplication, and modular exponentiation. It provides useful utility functions, such as endianness management and conversion routines. The big integer library is likely to change in future releases. Future updates to this library may change the programming interfaces.

This library has no run-time dependencies.

Recommended Usage

It is recommended that this library be used as a polyfill for the native Web Crypto API supported in modern browsers. It is strongly advised that you used the native browser crypto whenever available. It will be more thoroughly tested, more secure, and have significantly better performance. It is not recommended to use this library in a server type application.

To select native crypto, when available, you can use the following code:

// Select native crypto if supported
var crypto = window.crypto /*native*/ || window.msCrypto /*IE11 native*/ || window.msrCrypto; /*polyfill*/

// Call crypto functions
crypto.subtle.encrypt(...);

Library Files

Full library `/lib/msrCrypto.js` Minified library `/lib/msrCrypto.min.js`

Supported Algorithms

Encryption/Decryption:

• RSA-OAEP
• AES-GCM
• AES-CBC (_no longer recommended. Use AES-GCM. We continue support for compatibility_)

Digital Signature

• RSA-PSS
• RSA-PKCSv1.15
• HMAC
• ECDSA

Hash

• SHA-1 (_no longer recommended. Use SHA-2. We continue support for compatibility_)
• SHA-224
• SHA-256
• SHA-384
• SHA-512

Derive Key/Bits

• ECDH
• PBKDF2
• Concat-KDF
• HKDF

Wrap/Unwrap Key

• AES-GCM, AES-CBC, AES-KW, RSA-OAEP

Supported ECC curves:

• P-256, P-384, P-521, BN-254, NUMSP256D1, NUMSP256T1, NUMSP384D1, NUMSP384T1

Building the Library

>_While this library has npm build dependencies, it has no run-time dependencies._

You may build the library from the source files. The library is built using gulp from npm to concatenate many individual JavaScript files into a single library file. Run npm install from a command terminal to install the required _npm_ packages. gulpfile.js contains a list of scripts included in the build. You may remove scripts to create a subset of the library that supports fewer algorithms. Be aware, many scripts have dependencies on other scripts to function properly.

Building from Visual Studio Code:

>_These steps require that git, Node.js, and Visual Studio Code are installed on your system._

1. Clone the repo to a local folder git clone https://github.com/microsoft/MSR-JavaScript-Crypto.git 2. Open Visual Studio Code, select menu File->Open Folder... and open the cloned MSR-JavaScript-Crypto folder. 3. After the project has loaded, select menu Terminal->New Terminal to open a terminal window. 4. At the terminal prompt, run npm install to install the required Node.js modules to the project's node_modules folder. >You may need to reload the project for the build tools work properly: >Select menu View->Command Palette... (or F1) then enter Developer: Reload Window 5. Build the project: menu View->Command Palette... (or F1) then enter Tasks: Run Build Task. >Alternately you can use the _ctrl+shift+b_ keyboard shortcut. 6. The newly built library files will appear in the lib directory as msrCrypto.js and msrCrypto.min.js.

Building from the command line:

>_These steps require that git and Node.js are installed on your system._ 1. Clone the repo to a local folder git clone https://github.com/microsoft/MSR-JavaScript-Crypto.git 2. cd MSR-JavaScript-Crypto to enter the project directory. 3. npm install to install the required Node.js modules to the project's node_modules folder. 4. node_modules\.bin\gulp to build the library files. 5. The newly built library files will appear in the lib directory as msrCrypto.js and msrCrypto.min.js.

Additional Utilities

msrCrypto supplies a few data conversion functions that are not part of the Web Cryptography API spec. .textToBytes(String) converts a string to an Array of UTF-8 encoded bytes. .bytesToText(Array|ArrayBuffer|TypedArray) converts UTF-8 bytes into a string. .toBase64(Array|ArrayBuffer|TypedArray) converts byte data to a base-64 string. .fromBase64(String) converts a base-64 string into an Array of bytes.

Limitations and Security

Native crypto Developers should always use native platform crypto when available. Native crypto will have improved performance and offer additional security and memory protection not available in JavaScript. Modern browsers support the Web Crypto API.

Secret/private key data Secret key data is stored in JavaScript's memory and is potentially accessible to other scripts, applications, browser extensions, and developer tools. While key data may be stored outside of JavaScripts memory, the key data will be required in-memory by the algorithms running in JavaScript.

Side-channel protection We have taken steps to prevent...