A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.

To request an account, ask an autoconfirmed user on IRC (such as one of these permanent autoconfirmed members).

Difference between revisions of "Crypto"

From WHATWG Wiki
Jump to: navigation, search
m (fix typo)
(Make this read like a spec, update to modern IDL syntax, and fix header levels)
Line 1: Line 1:
=Overview=
+
==Overview==
  
 
This document describes a proposal for the window.crypto API.
 
This document describes a proposal for the window.crypto API.
  
=Definitions=
+
==Definitions==
  
==Cryptographically Random Values==
+
===Cryptographically Random Values===
  
A ''cryptographically random value'' is a value generated from a cryptographically strong pseudo-random number generator seeded with truly random values.  In practice, implementations should generate cryptographically random values using well-established cryptographic pseudo-random number generators, such as RC4, seeded with high-quality entropy, such as from an operating-system entropy source (e.g., ''/dev/urandom'').  This document provides no lower-bound on the information theoretic entropy present in cryptographically random values, but implementations should make a best effort to provide as much entropy as practicable.
+
A <b id=concept-cryptographically-random-values title=concept-cryptographically-random-values>cryptographically random value</b> is a value generated from a cryptographically strong pseudo-random number generator seeded with truly random values.  In practice, implementations should generate cryptographically random values using well-established cryptographic pseudo-random number generators, such as RC4, seeded with high-quality entropy, such as from an operating-system entropy source (e.g., ''/dev/urandom'').  This document provides no lower-bound on the information theoretic entropy present in cryptographically random values, but implementations should make a best effort to provide as much entropy as practicable.
  
=Interface=
+
==Interface==
  
 
<pre>
 
<pre>
[NoInterfaceObject]
 
 
interface Crypto {
 
interface Crypto {
 
   void getRandomValues(in ArrayBufferView array);
 
   void getRandomValues(in ArrayBufferView array);
 
};
 
};
  
[Supplemental, NoInterfaceObject]
+
partial interface Window {
interface Window {
 
 
   readonly attribute Crypto crypto;
 
   readonly attribute Crypto crypto;
 
};
 
};
 
</pre>
 
</pre>
  
=Methods=
+
==Methods==
  
==getRandomValues==
+
===getRandomValues===
  
The ''getRandomValues'' method fills ''array'' with random data.  Specifically, if ''array'' is an [http://www.khronos.org/registry/typedarray/specs/latest/#6 ArrayBufferView] of an integer type (i.e., Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, or Uint32Array), then all the elements of ''array'' are overwritten with ''cryptographically random values'' of the appropriate type.  If ''array'' is not of an integer type, ''getRandomValues'' throws a [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-domexception-type_mismatch_err TYPE_MISMATCH_ERR].
+
The <b id=dom-Crypto-getRandomValues title=dom-Crypto-getRandomValues><code>getRandomValues(<var>array</var>)</code></b> must run the following steps:
 +
# <var>array</var> is an [http://www.khronos.org/registry/typedarray/specs/latest/#6 ArrayBufferView]. If <var>array</var> is not of an integer type (i.e., Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, or Uint32Array), throw a [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-domexception-type_mismatch_err TYPE_MISMATCH_ERR] and abort these steps.
 +
# Overwrite all elements of <var>array</var> with [[#concept-cryptographically-random-values|cryptographically random values]] of the appropriate type.
  
 
[[Category:Proposals]]
 
[[Category:Proposals]]

Revision as of 12:14, 18 August 2011

Overview

This document describes a proposal for the window.crypto API.

Definitions

Cryptographically Random Values

A cryptographically random value is a value generated from a cryptographically strong pseudo-random number generator seeded with truly random values. In practice, implementations should generate cryptographically random values using well-established cryptographic pseudo-random number generators, such as RC4, seeded with high-quality entropy, such as from an operating-system entropy source (e.g., /dev/urandom). This document provides no lower-bound on the information theoretic entropy present in cryptographically random values, but implementations should make a best effort to provide as much entropy as practicable.

Interface

interface Crypto {
  void getRandomValues(in ArrayBufferView array);
};

partial interface Window {
  readonly attribute Crypto crypto;
};

Methods

getRandomValues

The getRandomValues(array) must run the following steps:

  1. array is an ArrayBufferView. If array is not of an integer type (i.e., Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, or Uint32Array), throw a TYPE_MISMATCH_ERR and abort these steps.
  2. Overwrite all elements of array with cryptographically random values of the appropriate type.