• Skip to main content
  • Select language
  • Skip to search
MDN Web Docs
  • Technologies
    • HTML
    • CSS
    • JavaScript
    • Graphics
    • HTTP
    • APIs / DOM
    • WebExtensions
    • MathML
  • References & Guides
    • Learn web development
    • Tutorials
    • References
    • Developer Guides
    • Accessibility
    • Game development
    • ...more docs
Archive of obsolete content
  1. MDN
  2. Archive of obsolete content
  3. Archived Mozilla and build documentation
  4. JavaScript crypto

JavaScript crypto

In This Article
  1. Using the Mozilla crypto object from JavaScript
    1. Handling smart card events
      1. Generating keys and issuing user certificates
    2. Overview of the new cert issuing process
    3. Typical use
      1. Signing text
      2. Loading PKCS #11 modules
      3. Mechanism flag definitions
      4. Cipher flags
      5. Miscellaneous

Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

Deprecated
This feature has been removed from the Web standards. Though some browsers may still support it, it is in the process of being dropped. Do not use it in old or new projects. Pages or Web apps using it may break at any time.

Warning: The features mentioned in this article are deleted proprietary Mozilla extensions, and are not supported in any other browser. They won't work in Firefox 34 or later. Use <keygen> or the future Web Crypto API instead.

Using the Mozilla crypto object from JavaScript

Mozilla defines a special JavaScript object to allow web pages access to certain cryptographic-related services. These services are a balance between the functionality web pages need and the requirement to protect users from malicious web sites. Most of these services are available via the DOM window object as window.crypto.

Services are provided to enable: smart card events, generating certificate requests, importing user certs, generating random numbers, logging out of your tokens, and signing text.

Handling smart card events

Web sites can make themselves more SmartCard friendly by listening for SmartCard insertion and removal events. To enable your document to receive these events, you must first tell the crypto system you are interested by setting window.crypto.enableSmartCardEvents to true. You can then register event handlers for these events with the document.addEventListener() method.

Two smart card related events are generated: smartcard-insert when SmartCards are inserted, and smartcard-remove when SmartCards are removed.

Web sites which use SSL clientAuth login could use the following code to refresh the page on token insertions and removals:

<!DOCTYPE html>
<p>...
<script>
function onSmartCardChange() {
  window.location.reload();
}
function register() {
  window.crypto.enableSmartCardEvents = true;
  document.addEventListener("smartcard-insert", onSmartCardChange, false);
  document.addEventListener("smartcard-remove", onSmartCardChange, false);
}
function deregister() {
  document.removeEventListener("smartcard-insert", onSmartCardChange, false);
  document.removeEventListener("smartcard-remove", onSmartCardChange, false);
}
document.body.onload = register;
document.body.onunload = deregister;
</script>

With the above example, your web site will automatically reload anytime a SmartCard is inserted or removed. This allows the page to automatically login and logout based on the presence of the SmartCard.

Generating keys and issuing user certificates

There are several crypto object methods used in generating keys for certificates: generateCRMFRequest(), importUserCertificates().

The generateCRMFRequest() function generates a key and creates a CRMF Request object. This object can be passed to a CA using a webform.

The importUserCertificates() function loads certificates into the NSS database or SmartCard if the corresponding key is found there.

The popChallengeResponse() function is not implemented.

Overview of the new cert issuing process

  1. User fills out enrollment form
  2. User action initiates script
  3. Script calls key generation method (generateCRMFRequest)
  4. Signing and Encryption keys are generated
  5. Encryption Private Key is wrapped with public key of Key Recovery Authority (KRA) (passed in in the form of a certificate as part of the script, and checked against a pre-installed certificate copy in the local certificate database)
  6. The public keys, wrapped encryption private key, and text string from the script (possibly containing naming or enrollment info) are signed by the user
  7. Signed blob is returned to the script
  8. Script submits signed blob and any other necessary info to the CA/RA
  9. CA/RA verifies signature on signed blob
  10. CA/RA validates identity of user
  11. CA/RA sends wrapped encryption private key to KRA
  12. KRA sends escrow verification back to CA
  13. CA creates and signs certificates
  14. CA sends certificates back to the user (importUserCertificates)

Typical use

The CA's enrollment page could look something like this:

<!DOCTYPE html>
<h2>Request a cert</h2>
<form name="ReqForm" method="post" action="http://your.ra.site.org">
<p><input type=hidden name=cert_request value="">
<p>Name: <input type=text name=name value="">
<p>Password: <input type=password name="password" value="">
<p><input type=submit Name="Send" value="Submit">
</form>
<script>
/* the following values could be filled in by the server CGI */
var authenticator = "server_magic";
var keyTransportCert = null;
var crmfObject = null;
var form = document.forms[0];
function validate()
{
  // generate keys for nsm.
  if (typeof(crypto.version) != "undefined") {
    crmfObject = crypto.generateCRMFRequest(
      "CN=" + form.name.value,
      form.password.value,
      authenticator,
      keyTransportCert,
      "setCRMFRequest();",
      1024,
      null,
      "rsa-dual-use");
  }
  return false;
}
function setCRMFRequest()
{
  form.cert_request.value = crmfObject.request;
  form.submit();
}
form.onsubmit = validate;
</script>

On completion of the request, the CA may submit a page that looks something like this:

<!DOCTYPE html>
<h2>Certificate Request Successful</h2>
<p>Hit 'load' to load your certificate</p>
<form name="ReqForm">
<p><input type=submit Name="Load" value="Submit"></p>
</form>
<script>
/* the following values could be filled in by the server CGI */
var nickname= "MyCertNickname";
var cert = "Mkjflakdjfiwjflaksufklasf ...";
var forceBackup = false;
function LoadCertificate()
{
  window.crypto.importUserCertificates(nickname, cert, forceBackup);
  return false;
}
document.forms[0].onsubmit = LoadCertificate;
</script>

Signing text

DOMString signText(DOMString stringToSign,
                   DOMString caOption /* ... */);

Loading PKCS #11 modules

long deletemodule(DOMString moduleName);
long addmodule(DOMString moduleName,
               DOMString libraryFullPath,
               long cryptoMechanismFlags,
               long cipherFlags);

Loads or removes a new PKCS #11 module. In the add case, the module will be placed in the NSS secmod.db database and will be loaded automatically on application restart. In the delete case, the module is removed from the NSS secmod.db. This function will issue a user prompt to confirm the operation before the add or delete actually occurs.

Parameters
moduleName
Name of the module.
libraryFullPath
The filename of the library prepended with its full path.
cryptoMechanismFlags
A bit vector indicating all cryptographic mechanisms should be turned on by default (see below).
cipherFlags
A bit vector indicating all SSL or S/MIME cipher functions supported by the module (see below).

Mechanism flag definitions

In general, most tokens should not set any of the cipher flags. Setting these flags means you want your token to supply the default implementation for these functions. Normally Mozilla uses its own internal module to supply these functions. These flags override that preference. If you choose to implement these flags, your module must supply the following additional functions for each flag:

  • PKCS11_MECH_FLAG: must support CKM_RSA_PKCS and CKM_RSA_X_509 and the following functions: C_WRAPKEY, C_ENCRYPT, C_SIGN, C_DECRYPT, C_UNWRAPKEY, C_VERIFYRECOVER, C_VERIFY, C_GENERATEKEYPAIR (2048, 1024, 512) size
  • PKCS11_MECH_DSA_FLAG: must support CKM_DSA and the following functions: C_SIGN, C_VERIFY, C_GENERATEKEYPAIR
  • PKCS11_MECH_RC2_FLAG: must support CKM_RC2_CBC and CKM_RC2_ECB and the following functions: C_GENERATEKEY, C_ENCRYPT, C_DECRYPT, C_WRAPKEY, C_UNWRAPKEY
  • PKCS11_MECH_RC4_FLAG: must support CKM_RC4_CBC and CKM_RC4_ECB and the following functions: C_GENERATEKEY, C_ENCRYPT, C_DECRYPT, C_WRAPKEY, C_UNWRAPKEY
  • PKCS11_MECH_DES_FLAG: must support CKM_CPMF_CBC, CKM_DES_CBC, CKM_DES3_CBC, CKM_CPMF_ECB, CKM_DES_ECB, CKM_DES3_ECB and the following functions: C_GENERATEKEY, C_ENCRYPT, C_DECRYPT, C_WRAPKEY, C_UNWRAPKEY
  • PKCS11_MECH_DH_FLAG: must support CKM_DH_PKCS_DERIVE and CKM_DH_KEY_PAIR_GEN and the following functions: C_DERIVEKEY, C_GENERATEKEYPAIR
  • PKCS11_MECH_MD5_FLAG: Hashing must be able to function without authentication.
  • PKCS11_MECH_SHA1_FLAG: Hashing must be able to function without authentication.
  • PKCS11_MECH_MD2_FLAG: Hashing must be able to function without authentication.*
  • PKCS11_RANDOM_FLAG: Use token's Random Number Generator.
    • Warning: Must be able to use without authentication. Many hardware random number generators are not as secure as the Netscape internal one. Do not select this value unless you can show that your random number generator is secure. Even so, it's highly discouraged.
  • PKCS11_PUB_READABLE_CERT_FLAG: This is the only flag most smart tokens should turn on. You can turn this flag on if:
    • the certs on your token can be read without authentication and,
    • the public key on your token can be found by ID, MODULUS, or VALUE and all your private keys have the associated public key.
      • Turning this flag on will illuminate a large number of password prompts for your token when looking up certs in Communicator.
PKCS11_MECH_RSA_FLAG           =  0x1<<0;
PKCS11_MECH_DSA_FLAG           =  0x1<<1;
PKCS11_MECH_RC2_FLAG           =  0x1<<2;
PKCS11_MECH_RC4_FLAG           =  0x1<<3;
PKCS11_MECH_DES_FLAG           =  0x1<<4;
PKCS11_MECH_DH_FLAG            =  0x1<<5; //Diffie-Hellman
PKCS11_MECH_SKIPJACK_FLAG      =  0x1<<6; //SKIPJACK algorithm as in Fortezza cards
PKCS11_MECH_RC5_FLAG           =  0x1<<7;
PKCS11_MECH_SHA1_FLAG          =  0x1<<8;
PKCS11_MECH_MD5_FLAG           =  0x1<<9;
PKCS11_MECH_MD2_FLAG           =  0x1<<10;
PKCS11_MECH_RANDOM_FLAG        =  0x1<<27; //Random number generator
PKCS11_PUB_READABLE_CERT_FLAG  =  0x1<<28; //Stored certs can be read off the token w/o logging in
PKCS11_DISABLE_FLAG            =  0x1<<30; //tell Mozilla to disable this slot by default

Cipher flags

Reserved

Important for CryptoMechanismFlags

0x1<<11, 0x1<<12, ... , 0x1<<26, 0x1<<29, and 0x1<<31 are reserved for internal use in Mozilla. Therefore, these bits should always be set to 0; otherwise, Mozilla might exhibit unpredictable behavior.

Important for CipherFlags

All values are reserved for internal use in Mozilla. Therefore, this flag should always be set to 0; otherwise, Mozilla might exhibit unpredictable behavior.

Example of CryptoMechanismFlags and CipherFlags

pkcs11MechanismFlags = PKCS11_MECH_DSA_FLAG | PKCS11_MECH_SKIPJACK_FLAG | PKCS11_MECH_RANDOM_FLAG;
pkcs11CipherFlags = 0;

Return Values

JS_OK_ADD_MODULE                  = 3   // Successfully added a module
JS_ERR_OTHER                      = -1  // Errors other than the following
JS_ERR_USER_CANCEL_ACTION         = -2  // User aborted an action
JS_ERR_INCORRECT_NUM_OF_ARGUMENTS = -3  // Calling a method w/ incorrect # of
                                        // arguments
JS_ERR_ADD_MODULE                 = -5  // Error adding a module
JS_ERR_BAD_MODULE_NAME            = -6  // The module name is invalid
JS_ERR_ADD_MODULE_DUPLICATE       = -10 // The module being installed has the
                                        // same name as one of the modules that
                                        // has already been installed

Miscellaneous

DOMString random(in long numBytes);

UnimplementedYou can use window.crypto.getRandomValues instead.

void logout();

Logs the user out of all the cryptographic tokens. The next private operation on any token will require the user password again. The SSL session cache is also cleared (from Firefox 1.5 upward).

This means the master password will be requested the next time a saved password will be accessed after this function is called. This also means the SSL client authentication state will be erased for SSL sites with client authentication, and a client certificate prompt will appear again the next time the user connects to the site.

Note: This function provides a convenient way to erase the SSL session state at the browser level, but in order to really guarantee that the state is erased, it is more secure to do it on the server side whenever possible.

void disableRightClick();

Unimplemented

Document Tags and Contributors

 Contributors to this page: javier1nc, jswisher, fscholz, teoli, kscarfone, Sheppy, evilpie, Ms2ger, Jmdesp, Sephr, ericjung, Lahmatiy, Jabez, Relyea, Dria, Callek, Shaver, Nickolay, Mouly
 Last updated by: javier1nc, Apr 22, 2016, 6:38:19 AM

  1. .htaccess ( hypertext access )
  2. <input> archive
  3. Add-ons
    1. Add-ons
    2. Firefox addons developer guide
    3. Interaction between privileged and non-privileged pages
    4. Tabbed browser
    5. bookmarks.export()
    6. bookmarks.import()
  4. Adding preferences to an extension
  5. An Interview With Douglas Bowman of Wired News
  6. Apps
    1. Apps
    2. App Development API Reference
    3. Designing Open Web Apps
    4. Graphics and UX
    5. Open web app architecture
    6. Tools and frameworks
    7. Validating web apps with the App Validator
  7. Archived Mozilla and build documentation
    1. Archived Mozilla and build documentation
    2. ActiveX Control for Hosting Netscape Plug-ins in IE
    3. Archived SpiderMonkey docs
    4. Autodial for Windows NT
    5. Automated testing tips and tricks
    6. Automatic Mozilla Configurator
    7. Automatically Handle Failed Asserts in Debug Builds
    8. BlackConnect
    9. Blackwood
    10. Bonsai
    11. Bookmark Keywords
    12. Building TransforMiiX standalone
    13. Chromeless
    14. Creating a Firefox sidebar extension
    15. Creating a Microsummary
    16. Creating a Mozilla Extension
    17. Creating a Release Tag
    18. Creating a Skin for Firefox/Getting Started
    19. Creating a Skin for Mozilla
    20. Creating a Skin for SeaMonkey 2.x
    21. Creating a hybrid CD
    22. Creating regular expressions for a microsummary generator
    23. DTrace
    24. Dehydra
    25. Developing New Mozilla Features
    26. Devmo 1.0 Launch Roadmap
    27. Download Manager improvements in Firefox 3
    28. Download Manager preferences
    29. Drag and Drop
    30. Embedding FAQ
    31. Embedding Mozilla in a Java Application using JavaXPCOM
    32. Error Console
    33. Exception logging in JavaScript
    34. Existing Content
    35. Extension Frequently Asked Questions
    36. Fighting Junk Mail with Netscape 7.1
    37. Firefox Sync
    38. Force RTL
    39. GRE
    40. Gecko Coding Help Wanted
    41. HTTP Class Overview
    42. Hacking wiki
    43. Help Viewer
    44. Helper Apps (and a bit of Save As)
    45. Hidden prefs
    46. How to Write and Land Nanojit Patches
    47. Introducing the Audio API extension
    48. Java in Firefox Extensions
    49. JavaScript crypto
    50. Jetpack
    51. Litmus tests
    52. Makefile.mozextension.2
    53. Microsummary topics
    54. Migrate apps from Internet Explorer to Mozilla
    55. Monitoring downloads
    56. Mozilla Application Framework
    57. Mozilla Crypto FAQ
    58. Mozilla Modules and Module Ownership
    59. Mozprocess
    60. Mozprofile
    61. Mozrunner
    62. Nanojit
    63. New Skin Notes
    64. Persona
    65. Plug-n-Hack
    66. Plugin Architecture
    67. Porting NSPR to Unix Platforms
    68. Priority Content
    69. Prism
    70. Proxy UI
    71. Remote XUL
    72. SXSW 2007 presentations
    73. Space Manager Detailed Design
    74. Space Manager High Level Design
    75. Standalone XPCOM
    76. Stress testing
    77. Structure of an installable bundle
    78. Supporting private browsing mode
    79. Table Cellmap
    80. Table Cellmap - Border Collapse
    81. Table Layout Regression Tests
    82. Table Layout Strategy
    83. Tamarin
    84. The Download Manager schema
    85. The life of an HTML HTTP request
    86. The new nsString class implementation (1999)
    87. TraceVis
    88. Treehydra
    89. URIScheme
    90. URIs and URLs
    91. Using Monotone With Mozilla CVS
    92. Using SVK With Mozilla CVS
    93. Using addresses of stack variables with NSPR threads on win16
    94. Venkman
    95. Video presentations
    96. Why Embed Gecko
    97. XML in Mozilla
    98. XPInstall
    99. XPJS Components Proposal
    100. XRE
    101. XTech 2005 Presentations
    102. XTech 2006 Presentations
    103. XUL Explorer
    104. XULRunner
    105. ant script to assemble an extension
    106. calICalendarView
    107. calICalendarViewController
    108. calIFileType
    109. xbDesignMode.js
  8. Archived open Web documentation
    1. Archived open Web documentation
    2. Browser Detection and Cross Browser Support
    3. Browser Feature Detection
    4. Displaying notifications (deprecated)
    5. E4X
    6. E4X Tutorial
    7. LiveConnect
    8. MSX Emulator (jsMSX)
    9. Old Proxy API
    10. Properly Using CSS and JavaScript in XHTML Documents
    11. Reference
    12. Scope Cheatsheet
    13. Server-Side JavaScript
    14. Sharp variables in JavaScript
    15. Standards-Compliant Authoring Tools
    16. Using JavaScript Generators in Firefox
    17. Window.importDialog()
    18. Writing JavaScript for XHTML
    19. XForms
    20. background-size
    21. forEach
  9. B2G OS
    1. B2G OS
    2. Automated Testing of B2G OS
    3. B2G OS APIs
    4. B2G OS add-ons
    5. B2G OS architecture
    6. B2G OS build prerequisites
    7. B2G OS phone guide
    8. Building B2G OS
    9. Building and installing B2G OS
    10. Building the B2G OS Simulator
    11. Choosing how to run Gaia or B2G
    12. Customization with the .userconfig file
    13. Debugging on Firefox OS
    14. Developer Mode
    15. Developing Firefox OS
    16. Firefox OS Simulator
    17. Firefox OS apps
    18. Firefox OS board guide
    19. Firefox OS developer release notes
    20. Firefox OS security
    21. Firefox OS usage tips
    22. Gaia
    23. Installing B2G OS on a mobile device
    24. Introduction to Firefox OS
    25. Mulet
    26. Open web apps quickstart
    27. Pandaboard
    28. PasscodeHelper Internals
    29. Porting B2G OS
    30. Preparing for your first B2G build
    31. Resources
    32. Running tests on Firefox OS: A guide for developers
    33. The B2G OS platform
    34. Troubleshooting B2G OS
    35. Using the App Manager
    36. Using the B2G emulators
    37. Web Bluetooth API (Firefox OS)
    38. Web Telephony API
    39. Web applications
  10. Beginner tutorials
    1. Beginner tutorials
    2. Creating reusable content with CSS and XBL
    3. Underscores in class and ID Names
    4. XML data
    5. XUL user interfaces
  11. Case Sensitivity in class and id Names
  12. Creating a dynamic status bar extension
  13. Creating a status bar extension
  14. Gecko Compatibility Handbook
  15. Getting the page URL in NPAPI plugin
  16. Index
  17. Inner-browsing extending the browser navigation paradigm
  18. Install.js
  19. JXON
  20. List of Former Mozilla-Based Applications
  21. List of Mozilla-Based Applications
  22. Localizing an extension
  23. MDN
    1. MDN
    2. Content kits
  24. MDN "meta-documentation" archive
    1. MDN "meta-documentation" archive
    2. Article page layout guide
    3. Blog posts to integrate into documentation
    4. Current events
    5. Custom CSS classes for MDN
    6. Design Document
    7. DevEdge
    8. Developer documentation process
    9. Disambiguation
    10. Documentation Wishlist
    11. Documentation planning and tracking
    12. Editing MDN pages
    13. Examples
    14. Existing Content/DOM in Mozilla
    15. External Redirects
    16. Finding the right place to document bugs
    17. Getting started as a new MDN contributor
    18. Landing page layout guide
    19. MDN content on WebPlatform.org
    20. MDN page layout guide
    21. MDN subproject list
    22. Needs Redirect
    23. Page types
    24. RecRoom documentation plan
    25. Remove in-content iframes
    26. Team status board
    27. Trello
    28. Using the Mozilla Developer Center
    29. Welcome to the Mozilla Developer Network
    30. Writing chrome code documentation plan
    31. Writing content
  25. MMgc
  26. Makefile - .mk files
  27. Marketplace
    1. Marketplace
    2. API
    3. Monetization
    4. Options
    5. Publishing
  28. Mozilla release FAQ
  29. Newsgroup summaries
    1. Newsgroup summaries
    2. Format
    3. Mozilla.dev.apps.firefox-2006-09-29
    4. Mozilla.dev.apps.firefox-2006-10-06
    5. mozilla-dev-accessibility
    6. mozilla-dev-apps-calendar
    7. mozilla-dev-apps-firefox
    8. mozilla-dev-apps-thunderbird
    9. mozilla-dev-builds
    10. mozilla-dev-embedding
    11. mozilla-dev-extensions
    12. mozilla-dev-i18n
    13. mozilla-dev-l10n
    14. mozilla-dev-planning
    15. mozilla-dev-platform
    16. mozilla-dev-quality
    17. mozilla-dev-security
    18. mozilla-dev-tech-js-engine
    19. mozilla-dev-tech-layout
    20. mozilla-dev-tech-xpcom
    21. mozilla-dev-tech-xul
    22. mozilla.dev.apps.calendar
    23. mozilla.dev.tech.js-engine
  30. Obsolete: XPCOM-based scripting for NPAPI plugins
  31. Plugins
    1. Plugins
    2. Adobe Flash
    3. External resources for plugin creation
    4. Logging Multi-Process Plugins
    5. Monitoring plugins
    6. Multi-process plugin architecture
    7. NPAPI plugin developer guide
    8. NPAPI plugin reference
    9. Samples and Test Cases
    10. Shipping a plugin as a Toolkit bundle
    11. Supporting private browsing in plugins
    12. The First Install Problem
    13. Writing a plugin for Mac OS X
    14. XEmbed Extension for Mozilla Plugins
  32. SAX
  33. Security
    1. Security
    2. Digital Signatures
    3. Encryption and Decryption
    4. Introduction to Public-Key Cryptography
    5. Introduction to SSL
    6. NSPR Release Engineering Guide
    7. SSL and TLS
  34. Solaris 10 Build Prerequisites
  35. Sunbird Theme Tutorial
  36. Table Reflow Internals
  37. Tamarin Tracing Build Documentation
  38. The Basics of Web Services
  39. Themes
    1. Themes
    2. Building a Theme
    3. Common Firefox theme issues and solutions
    4. Creating a Skin for Firefox
    5. Making sure your theme works with RTL locales
    6. Theme changes in Firefox 2
    7. Theme changes in Firefox 3
    8. Theme changes in Firefox 3.5
    9. Theme changes in Firefox 4
  40. Updating an extension to support multiple Mozilla applications
  41. Using IO Timeout And Interrupt On NT
  42. Using SSH to connect to CVS
  43. Using workers in extensions
  44. WebVR
    1. WebVR
    2. WebVR environment setup
  45. XQuery
  46. XUL Booster
  47. XUL Parser in Python