Bug 23728, Bug 24878, Bug 25436 - Formally specify the algorithm normalization process.
This is accomplished through reviving the concept of 'registered algorithms', for the
purpose of explicitly defining how conversion from ECMAScript objects to IDL types
takes place.
This allows individual algorithms to eliminate common boilerplate, as well as make
sure that handling for (optional fields, CryptoOperationData) are consistently
adhered to.
It's a step further into treating algorithms as "internal objects" with state, which
is to allow for greater extensibility (by describing lookups in internal maps),
so that new algorithms do not need to update the 'main' specification.
In the course of this, two changes were made, neither of which fundamentally alters
the API in a way that users can distinguish - the introduction of a typedef called
HashAlgorithmIdentifier that is an AlgorithmIdentifier, and simply used for specifying
how nested hash algorithms work (which are a sort of special case), and the restructuring
of the algorithms section to better explain and explore these concepts.
--- a/spec/Overview-WebCryptoAPI.xml Mon Jun 16 00:00:00 2014 -0700
+++ b/spec/Overview-WebCryptoAPI.xml Mon Jun 16 00:00:00 2014 -0700
@@ -925,8 +925,9 @@
specify the desired operation.
</p>
<x:codeblock language="idl">
-<span class="comment">// TBD: <a href="http://www.w3.org/2012/webcrypto/track/issues/28">ISSUE-28</a></span>
-typedef (<a href="#dfn-Algorithm">Algorithm</a> or DOMString) <dfn id="dfn-AlgorithmIdentifier">AlgorithmIdentifier</dfn>;
+typedef (object or DOMString) <dfn id="dfn-AlgorithmIdentifier">AlgorithmIdentifier</dfn>;
+
+typedef <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> <dfn id="dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</dfn>;
dictionary <dfn id="dfn-Algorithm">Algorithm</dfn> {
DOMString <a href="#dfn-Algorithm-name">name</a>;
@@ -1315,6 +1316,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>encrypt</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1335,28 +1350,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>key</var> and <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the
- encrypt operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>key</var> does not contain an entry that is <code>"encrypt"</code>, then <a
href="#concept-return-an-error">return an error</a> named <a
@@ -1406,6 +1399,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>decrypt</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1426,28 +1433,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>key</var> and <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the decrypt
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>key</var> does not contain an entry that is <code>"decrypt"</code>, then <a
href="#concept-return-an-error">return an error</a> named <a
@@ -1497,6 +1482,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>sign</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1517,28 +1516,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>key</var> and <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the sign
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>key</var> does not contain an entry that is <code>"sign"</code>, then <a
href="#concept-return-an-error">return an error</a> named <a
@@ -1586,6 +1563,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>verify</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>data</var> be the result of <a href="#concept-clone-CryptoOperationData">
cloning the data</a> of the <code>data</code> parameter passed to the
<a href="#dfn-SubtleCrypto-method-verify">verify</a> method.
@@ -1613,28 +1604,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>key</var>, <var>data</var> and <var>signature</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the verify
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>key</var> does not contain an entry that is <code>"verify"</code>, then <a
href="#concept-return-an-error">return an error</a> named <a
@@ -1682,6 +1651,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>digest</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1702,28 +1685,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the digest
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
Let <var>result</var> be the result of performing the digest
operation specified by <var>normalizedAlgorithm</var> using
<var>algorithm</var>, with <var>data</var>
@@ -1758,6 +1719,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>generateKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1778,28 +1753,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>extractable</var> and <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the generate
- key operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If <var>usages</var> includes a value that is not a
<a href="#dfn-RecognizedKeyUsage">recognized key usage value</a>,
then <a href="#concept-return-an-error">return an error</a> named
@@ -1842,6 +1795,34 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>deriveKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>normalizedDerivedKeyAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>derivedKeyType</var> and <code>op</code> set to
+ <code>importKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1862,39 +1843,19 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>baseKey</var>, <var>extractable</var> and <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the derive bits
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedDerivedKeyAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>derivedKeyType</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
+ <var>normalizedAlgorithm</var> does not identify a <a
+ href="#algorithms">registered algorithm</a> that supports the derive bits
+ operation, then <a href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
<li>
<p>
If the <a href="#dfn-Algorithm-name">name</a> member of
<var>normalizedDerivedKeyAlgorithm</var> does not identify a
<a href="#algorithms">registered algorithm</a> that supports the get key length
- and import key operations, then <a href="#concept-return-an-error">return an error</a> named
+ operation, then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
</p>
</li>
@@ -1965,6 +1926,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>deriveBits</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1985,28 +1960,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>baseKey</var> and <var>length</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the derive bits
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>baseKey</var> does not contain an entry that is <code>"deriveBits"</code>,
then <a href="#concept-return-an-error">return an error</a> named <a
@@ -2050,6 +2003,20 @@
</p>
</li>
<li>
+ <p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>importKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
<dl class="switch">
<dt>
If <var>format</var> is equal to the string <code>raw</code>,
@@ -2094,29 +2061,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>format</var>, <var>keyData</var>,
- <var>extractable</var> and <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the import key
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If <var>format</var> is not
a <a href="#dfn-RecognizedKeyFormats">recognized key
format value</a>, then <a href="#concept-return-an-error">return an error</a> named
@@ -2186,19 +2130,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>format</var> and <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
If <var>format</var> is not a
<a href="#dfn-RecognizedKeyFormats">recognized key
format value</a>, then <a href="#concept-return-an-error">return an error</a> named
@@ -2207,11 +2138,12 @@
</li>
<li>
<p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the export key
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ If the <a href="#dfn-Algorithm-name">name</a> member of of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> does not identify a <a href="#algorithms">registered algorithm</a>
+ that supports the export key operation, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
</p>
</li>
<li>
@@ -2256,6 +2188,28 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>wrapKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>encrypt</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -2276,19 +2230,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>format</var>, <var>key</var> and <var>wrappingKey</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
If the <a href="#dfn-Algorithm-name">name</a> member of
<var>normalizedAlgorithm</var> does not identify a
<a href="#algorithms">registered algorithm</a> that supports the encrypt or wrap
@@ -2455,6 +2396,42 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>unwrapKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>decrypt</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>normalizedKeyAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>unwrappedKeyAlgorithm</var> and <code>op</code> set to
+ <code>importKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedKeyAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -2475,46 +2452,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>format</var>, <var>wrappedKey</var>, <var>unwrappingKey</var>,
- <var>extractable</var> and <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the unwrap key or
- decrypt
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedKeyAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>unwrappedKeyAlgorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedKeyAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the importKey
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>unwrappingKey</var> does not contain an entry that is
<code>"unwrapKey"</code>, then <a href="#concept-return-an-error">return an
@@ -2774,6 +2711,488 @@
<div id="algorithms" class="section">
<h2>Algorithms</h2>
+ <div id="algorithm-overview" class="section">
+ <h3>Overview</h3>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ In addition to providing a common interface to perform cryptographic operations, by
+ way of the <a href="#dfn-SubtleCrypto">SubtleCrypto</a> interface, this specification
+ also provides descriptions for a variety of algorithms that authors may wish to use and
+ that User Agents may choose to implement. This includes a selection of commonly-deployed
+ symmetric and asymmetric algorithms, key derivation mechanisms, and methods for wrapping
+ and unwrapping keys. Further, this specification defines a process to allow additional
+ specifications to introduce additional cryptographic algorithms.
+ </p>
+ </div>
+
+ <div id="algorithm-concepts" class="section">
+ <h3>Concepts</h3>
+ <div id="algorithm-concepts-naming" class="section">
+ <h4>Naming</h4>
+ <p>
+ Every cryptographic algorithm defined for use with the Web Cryptography API
+ <span class="RFC2119">MUST</span> have a unique name, referred to as its
+ <dfn id="recognized-algorithm-name">recognized algorithm name</dfn>, such that no
+ other specification defines the same case-sensitive string for use with the
+ Web Cryptography API.
+ </p>
+ </div>
+ <div id="algorithm-concepts-operations" class="section">
+ <h4>Supported Operations</h4>
+ <p>
+ Every cryptographic algorithm defined for use with the Web Cryptography API has a list
+ of <dfn id="supported-operation">supported operations</dfn>, which are a set of
+ sub-algorithms to be invoked by the <a href="#dfn-SubtleCrypto">SubtleCrypto</a>
+ interface in order to perform the desired cryptographic operation. This specification
+ makes use of the following operations:
+ </p>
+ <ul>
+ <li>encrypt</li>
+ <li>decrypt</li>
+ <li>sign</li>
+ <li>verify</li>
+ <li>deriveBits</li>
+ <li>wrapKey</li>
+ <li>unwrapKey</li>
+ <li>generateKey</li>
+ <li>importKey</li>
+ <li>exportKey</li>
+ <li>getLength</li>
+ </ul>
+ <p>
+ If a given algorithm specification does not list a particular operation as supported,
+ or explicitly lists an operation as not-supported, then the User Agent
+ <span class="RFC2119">MUST</span> behave as if the invocation of the sub-algorithm
+ threw a NotSupportedError.
+ </p>
+ </div>
+ <div id="algorithm-concepts-normalization" class="section">
+ <h4>Normalization</h4>
+ <p>
+ Every cryptographic algorithm defined for use with the Web Cryptography API <span
+ class="RFC2119">MUST</span> define, for every <a href="#supported-operation">
+ supported operation</a>, the IDL type to use for <a
+ href="#concept-algorithm-normalization">algorithm normalization</a>, as well as the
+ IDL type or types of the return values of the sub-algorithms.
+ </p>
+ </div>
+ </div>
+
+ <div id="algorithm-conventions" class="section">
+ <h3>Specification Conventions</h3>
+ <p>
+ Every cryptographic algorithm definition within this specification employs the following
+ specification conventions. A section, titled <em>"Registration"</em>, will include the
+ <a href="#recognized-algorithm-name">recognized algorithm name</a>. Additionally, it
+ includes a table, which will list each of the <a href="#supported-operation">supported
+ operations</a> as rows, identified by the <em>Operation</em> column. The contents of the
+ <em>Parameters</em> column for a given row will contain the IDL type to use for <a
+ href="#concept-algorithm-normalization">algorithm normalization</a> for that operation,
+ and the contents of the <em>Result</em> column for that row indicate the IDL type that
+ results from performing the supported operation.
+ </p>
+ <p>
+ If a conforming User Agent implements an algorithm, it
+ <span class="RFC2119">MUST</span> implement all of the <a href="#supported-operation">
+ supported operations</a> and <span class="RFC2119">MUST</span> return the IDL type
+ specified.
+ </p>
+ <p>
+ Additionally, upon initialization, conforming User Agents must perform the
+ <a href="#concept-define-an-algorithm">define an algorithm</a> steps for each of
+ the supported operations, registering their IDL parameter type as indicated.
+ </p>
+ </div>
+
+ <div id="algorithm-normalizing" class="section">
+ <h3>Algorithm Normalization</h3>
+ <div id="algorithm-normalizing-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative</p>
+ <p>
+ The <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> typedef permits
+ algorithms to either be specified as a <a href="#dfn-DOMString">DOMString</a> or an
+ object. The usage of <a href="#dfn-DOMString">DOMString</a> is to permit authors a
+ short-hand for noting algorithms that have no parameters (e.g. SHA-1), as well as to
+ permit 'aliases' for well-known configurations of algorithms, rather than require
+ authors explicitly specify all of the parameters. The usage of object is to allow an <a
+ href="#dfn-Algorithm">Algorithm</a> (or appropriate subclass) to be specified, which
+ contains all of the associated parameters for an object.
+ </p>
+ <p>
+ Because of this, it's necessary to define the algorithm for converting an <a
+ href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> into an appropriate dictionary
+ that is usable with this API. This algorithm must be extensible, so as to allow new
+ cryptographic algorithms to be added, and consistent, so that Web IDL type mapping can
+ occur before any control is returned to the calling script, which would potentially
+ allow the mutation of parameters or the script environment.
+ </p>
+ </div>
+
+ <div id="algorithm-normalizing-internal" class="section">
+ <h4>Internal State Objects</h4>
+ <p>
+ This specification makes use of an internal object,
+ [[<dfn id="dfn-supportedAlgorithms">supportedAlgorithms</dfn>]]. This internal object is
+ not exposed to applications.
+ </p>
+ <p>
+ Because this value is not exposed to applications, the exact type is not specified.
+ It is only required to behave as an associative container of key/value pairs, where
+ comparisons of keys are performed in a case-sensitive manner.
+ </p>
+ <p>
+ The initial contents of this internal object are as follows:
+ </p>
+ <ol>
+ <li>
+ <p>
+ For each value, <var>v</var> in the List of <a
+ href="#supported-operation">supported operations</a>, perform the following:
+ </p>
+ <ol>
+ <li>
+ Initialize a new associative container, <var>container</var>
+ </li>
+ <li>
+ Set the <code>aliases</code> key of <var>container</var> to a new associative
+ container.
+ </li>
+ <li>
+ Set the <code>algorithms</code> key of <var>container</var> to a new associative
+ container.
+ </li>
+ <li>
+ Set the <var>v</var> key of the internal object to <var>container</var>.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ </div>
+
+ <div id="algorithm-normalizing-define-an-algorithm" class="section">
+ <h4>Defining an Algorithm</h4>
+ <p>
+ The <dfn id="concept-define-an-algorithm">define an algorithm</dfn> algorithm is used
+ by specification authors to indicate how a user agent should normalize arguments for a
+ particular algorithm. Its input is an algorithm name <var>alg</var>, represented as a
+ DOMString, operation name <var>op</var>, represented as a DOMString, and desired IDL
+ dictionary type <var>type</var>. The algorithm behaves as follows:
+ </p>
+ <ol>
+ <li>
+ Let <var>algorithmsAndAliases</var> be the associative container stored at the
+ <var>op</var> key of [[<a href="#dfn-supportedAlgorithms">supportedAlgorithms</a>]].
+ </li>
+ <li>
+ Let <var>registeredAlgorithms</var> be the value of the <code>algorithms</code> key of
+ <var>algorithmsAndAliases</var>.
+ </li>
+ <li>
+ Set the <var>alg</var> key of <var>registeredAlgorithms</var> to the IDL dictionary
+ type <var>type</var>.
+ </li>
+ </ol>
+ </div>
+
+ <div id="algorithm-normalizing-define-an-alias" class="section">
+ <h4>Defining an Alias</h4>
+ <p>
+ The <dfn id="concept-define-an-alias">define an alias</dfn> algorithm is used by
+ specification authors to indicate how a user agent should normalize aliases for
+ particular algorithms. Its input is an algorithm alias <var>alg</var>, represented as
+ a DOMString, operation name <var>op</var>, represented as a DOMString, and internal
+ IDL object <var>default</var>. The algorithm behaves as follows:
+ </p>
+ <ol>
+ <li>
+ Let <var>algorithmsAndAliases</var> be the associative container stored at the
+ <var>op</var> key of [[<a href="#dfn-supportedAlgorithms">supportedAlgorithms</a>]].
+ </li>
+ <li>
+ Let <var>registeredAlgorithms</var> be the value of the <code>algorithms</code> key of
+ <var>algorithmsAndAliases</var>.
+ </li>
+ <li>
+ Set the <var>alg</var> key of <var>registeredAlgorithms</var> to <var>default</var>.
+ </li>
+ </ol>
+ </div>
+
+ <div id="algorithm-normalizing-normalize-an-algorithm" class="section">
+ <h4>Normalizing an algorithm</h4>
+ <p>
+ The <dfn id="dfn-normalize-an-algorithm">normalize an algorithm</dfn> algorithm defines
+ a process for coercing inputs to a targeted IDL dictionary type, after Web IDL
+ conversion has occurred. It is designed to be extensible, to allow future specifications
+ to define additional algorithms, as well as safe for use with Promises. Its input is an
+ operation name <var>op</var> and an <a
+ href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> <var>alg</var>. Its output is
+ either an IDL dictionary type or an error. It behaves as follows:
+ </p>
+ <dl class="switch">
+ <dt>If <var>alg</var> is an instance of a DOMString:</dt>
+ <dd>
+ <ol>
+ <li>
+ Let <var>algorithmsAndAliases</var> be the associative container stored at the
+ <code>op</code> key of [[<a
+ href="#dfn-supportedAlgorithms">supportedAlgorithms</a>]].
+ </li>
+ <li>
+ If <var>algorithmAndAliases</var> is <code>undefined</code>, return a
+ new <code>NotSupportedError</code> and terminate this algorithm.
+ </li>
+ <li>
+ Let <var>registeredAliases</var> be the associative container stored at the
+ <code>aliases</code> key of <var>algorithmsAndAliases</var>.
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <var>alg</var> key of <var>registeredAliases</var> is
+ <code>undefined</code>:
+ </dt>
+ <dd>
+ Return the result of running the <a
+ href="#dfn-normalize-an-algorithm">normalize an algorithm</a> algorithm, with
+ the <code>alg</code> set to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ dictionary whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is
+ <var>alg</var>, and with the <code>op</code> set to <var>op</var>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ Return the internal IDL object stored in the <var>alg</var> key of
+ <var>registeredAliases</var>.
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>alg</var> is an IDL object:</dt>
+ <dd>
+ <ol>
+ <li>
+ Let <var>algorithmsAndAliases</var> be the associative container stored at the
+ <code>op</code> key of [[<a
+ href="#dfn-supportedAlgorithms">supportedAlgorithms</a>]].
+ </li>
+ <li>
+ If <var>algorithmAndAliases</var> is <code>undefined</code>, return a
+ new <code>NotSupportedError</code> and terminate this algorithm.
+ </li>
+ <li>
+ Let <var>registeredAlgorithms</var> be the associative container stored at the
+ <code>algorithms</code> key of <var>algorithmsAndAliases</var>.
+ </li>
+ <li>
+ Let <var>initialAlg</var> be the result of converting the ECMAScript object
+ represented by <var>alg</var> to the IDL dictionary type <a
+ href="#dfn-Algorithm">Algorithm</a>, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </li>
+ <li>
+ If an error occurred, return the error and terminate this algorithm.
+ </li>
+ <li>
+ If the <a href="#dfn-Algorithm-name">name</a> attribute of <var>initialAlg</var>
+ is not present, return a new <code>SyntaxError</code> and terminate this
+ algorithm.
+ </li>
+ <li>
+ Let <var>algName</var> be the value of the <a href="#dfn-Algorithm-name">name</a>
+ attribute of <var>initialAlg</var>.
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <var>algName</var> key of <var>registeredAlgorithms</var> is
+ <code>undefined</code>:
+ </dt>
+ <dd>
+ Return a new <code>NotSupportedError</code> and terminate this algorithm.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ Let <var>desiredType</var> be the IDL dictionary type stored in the
+ <var>algName</var> key of <var>registeredAlgorithms</var>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ Let <var>normalizedAlgorithm</var> be the result of converting the ECMAScript
+ object represented by <var>alg</var> to the IDL dictionary type
+ <var>desiredType</var>, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </li>
+ <li>
+ If an error occurred, return the error and terminate this algorithm.
+ </li>
+ <li>
+ Let <var>dictionaries</var> be a list consisting of the IDL dictionary type
+ <var>desiredType</var> and all of <var>desiredType</var>'s inherited dictionaries,
+ in order from least to most derived.
+ </li>
+ <li>
+ <p>
+ For each dictionary <var>dictionary</var> in <var>dictionaries</var>:
+ </p>
+ <ol>
+ <li>
+ <p>
+ For each dictionary member <var>member</var> declared on
+ <var>dictionary</var>, in order:
+ </p>
+ <ol>
+ <li>
+ If <var>member</var> is not nullable, and is not present, return a new
+ <code>SyntaxError</code> and terminate this algorithm.
+ </li>
+ <li>
+ If <var>member</var> is nullable, and is not present, return to
+ iterating the next dictionary member <var>member</var>, stopping further
+ processing of this <var>member</var>.
+ </li>
+ <li>
+ Let <var>key</var> be the identifier of <var>member</var>.
+ </li>
+ <li>
+ Let <var>idlValue</var> be the value of the dictionary member with
+ key name of <var>key</var> on <var>normalizedAlgorithm</var>.
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>member</var> is of the type
+ <a href="#dfn-CryptoOperationData">CryptoOperationData</a> and is
+ present:
+ </dt>
+ <dd>
+ Set the dictionary member on <var>normalizedAlgorithm</var> with key
+ name <var>key</var> to a <a
+ href="#concept-clone-CryptoOperationData">clone of
+ <var>idlValue</var></a>, replacing the current value.
+ </dd>
+ <dt>
+ If <var>member</var> is of the type
+ <a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a>:
+ </dt>
+ <dd>
+ Set the dictionary member on <var>normalizedAlgorithm</var> with key
+ name <var>key</var> to the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>,
+ with the <code>alg</code> set to <var>idlValue</var> and the
+ <code>op</code> set to <code>"digest"</code>.
+ </dd>
+ <dt>
+ If <var>member</var> is of the type
+ <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a>:
+ </dt>
+ <dd>
+ Set the dictionary member on <var>normalizedAlgorithm</var> with key
+ name <var>key</var> to the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>,
+ with the <code>alg</code> set to <var>idlValue</var> and the
+ <code>op</code> set to <var>op</var>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ If an error occurred, return the error and terminate this algorithm.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ <li>
+ Return <var>normalizedAlgorithm</var>.
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+
+ </div>
+
+ <div id="algorithm-recommendations" class="section">
+ <h3>Recommendations</h3>
+ <p class="norm">This section is non-normative.</p>
+ <div id="algorithm-recommendations-authors" class="section">
+ <h4>For Authors</h4>
+ <p>
+ As this API is meant to be extensible, in order to keep up with future developments
+ within cryptography, there are no algorithms that conforming user agents are required
+ to implement. As such, authors should check to see what algorithms are currently
+ recommended and supported by implementations.
+ </p>
+ <p>
+ As highlighted in the <a href="#security-considerations">Security Considerations</a>,
+ even cryptographic algorithms that might be considered strong for one purpose may be
+ insufficient when used with another purpose. Authors should therefore proceed with
+ extreme caution before inventing new cryptographic protocols.
+ </p>
+ <p>
+ Additionally, this specification includes several algorithms which, in their default
+ usage, can result in cryptographic vulnerabilities. While these concerns may be
+ mitigated, such as through the combination and composition with additional algorithms
+ provided by this specification, authors should proceed with caution and review the
+ relevant cryptographic literature before using a given algorithm. The inclusion of
+ algorithms within this specification is not an indicator of their suitability for any
+ or all purpose, and instead merely serve to provide as a specification for how a
+ conforming User Agent must implement the given algorithm, if it choses to implement
+ the algorithm.
+ </p>
+ </div>
+ <div id="algorithm-recommendations-implementers" class="section">
+ <h4>For Implementers</h4>
+ <p>
+ In order to promote interoperability for developers, this specification includes a
+ list of suggested algorithms. These are considered to be the most widely used
+ algorithms in practice at the time of writing, and therefore provide a good starting
+ point for initial implementations of this specification. The suggested algorithms are:
+ </p>
+ <ul>
+ <li>
+ <a href="#hmac">HMAC</a> using <a href="#alg-sha-1">SHA-1</a>
+ </li>
+ <li>
+ <a href="#hmac">HMAC</a> using <a href="#alg-sha-256">SHA-256</a>
+ </li>
+ <li>
+ <a href="#rsassa-pkcs1">RSASSA-PKCS1-v1_5</a> using
+ <a href="#alg-sha-256">SHA-1</a>
+ </li>
+ <li>
+ <a href="#rsa-pss">RSA-PSS</a> using <a href="#alg-sha-256">SHA-256</a>
+ and MGF1 with <a href="#alg-sha-256">SHA-256</a>.
+ </li>
+ <li>
+ <a href="#rsa-oaep">RSA-OAEP</a> using <a href="#alg-sha-256">SHA-256</a>
+ and MGF1 with <a href="#alg-sha-256">SHA-256</a>.
+ </li>
+ <li>
+ <a href="#ecdsa">ECDSA</a> using <a href="#dfn-NamedCurve-p256">P-256</a>
+ curve and <a href="#alg-sha-256">SHA-256</a>
+ </li>
+ <li><a href="#aes-cbc">AES-CBC</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div id="algorithm-overview" class="section">
+ <h2>Algorithm Overview</h2>
+ <p class="norm">The following section is non-normative.</p>
+ <p>
+ The table below contains an overview of the algorithms described within this
+ specification, as well as the set of operations the algorithm may be used with.
+ </p>
+ <p class="note">
+ Application developers and script authors should not interpret this table as a
+ recommendation for the use of particular algorithms. Instead, it simply documents what
+ operations are supported. Authors should refer to the <a
+ href="#security-developers">Security considerations for authors</a> section of this
+ document to better understand the risks and concerns that may arise when using certain
+ algorithms.
+ </p>
<div class="ednote">
<p>
Note: All algorithms listed should be considered as "features at risk",
@@ -2787,13558 +3206,12677 @@
altered in future revisions.
</p>
</div>
- <div id="algorithms-index" class="section">
- <h3>Registered algorithms</h3>
+ <table>
+ <thead>
+ <tr>
+ <th>Algorithm name</th>
+ <th scope="col">encrypt</th>
+ <th scope="col">decrypt</th>
+ <th scope="col">sign</th>
+ <th scope="col">verify</th>
+ <th scope="col">digest</th>
+ <th scope="col">generateKey</th>
+ <th scope="col">deriveKey</th>
+ <th scope="col">deriveBits</th>
+ <th scope="col">importKey</th>
+ <th scope="col">exportKey</th>
+ <th scope="col">wrapKey</th>
+ <th scope="col">unwrapKey</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><a href="#rsassa-pkcs1">RSASSA-PKCS1-v1_5</a></td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#rsa-pss">RSA-PSS</a></td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#rsa-oaep">RSA-OAEP</a></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#ecdsa">ECDSA</a></td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#ecdh">ECDH</a></td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#aes-ctr">AES-CTR</a></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#aes-cbc">AES-CBC</a></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#aes-cmac">AES-CMAC</a></td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#aes-gcm">AES-GCM</a></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#aes-cfb">AES-CFB</a></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#aes-kw">AES-KW</a></td>
+ <td></td>
+ <td></td>
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#hmac">HMAC</a></td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#dh">DH</a></td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#sha">SHA-1</a></td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#sha">SHA-256</a></td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#sha">SHA-384</a></td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#sha">SHA-512</a></td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#concatkdf">CONCAT</a></td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#hkdf-ctr">HKDF-CTR</a></td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td />
+ </tr>
+ <tr>
+ <td><a href="#pbkdf2">PBKDF2</a></td>
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td />
+ <td>✔</td>
+ <td>✔</td>
+ <td />
+ <td />
+ <td />
+ <td />
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <div id="rsassa-pkcs1" class="section">
+ <h3>RSASSA-PKCS1-v1_5</h3>
+ <div id="rsassa-pkcs1-description" class="section">
+ <h4>Description</h4>
+ <p>
+ The <code>"RSASSA-PKCS1-v1_5"</code> algorithm identifier is used to perform
+ signing and verification using the RSASSA-PKCS1-v1_5 algorithm specified in
+ [<cite><a href="#RFC3447">RFC3447</a></cite>].
+ </p>
+ </div>
+ <div id="rsassa-pkcs1-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"RSASSA-PKCS1-v1_5"</code>.
+ </p>
<table>
<thead>
<tr>
- <th>Algorithm name</th>
- <th scope="col">encrypt</th>
- <th scope="col">decrypt</th>
- <th scope="col">sign</th>
- <th scope="col">verify</th>
- <th scope="col">digest</th>
- <th scope="col">generateKey</th>
- <th scope="col">deriveKey</th>
- <th scope="col">deriveBits</th>
- <th scope="col">importKey</th>
- <th scope="col">exportKey</th>
- <th scope="col">wrapKey</th>
- <th scope="col">unwrapKey</th>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
</tr>
</thead>
<tbody>
<tr>
- <td><a href="#rsassa-pkcs1">RSASSA-PKCS1-v1_5</a></td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#rsa-pss">RSA-PSS</a></td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#rsa-oaep">RSA-OAEP</a></td>
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#ecdsa">ECDSA</a></td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#ecdh">ECDH</a></td>
- <td />
- <td />
- <td />
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#aes-ctr">AES-CTR</a></td>
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#aes-cbc">AES-CBC</a></td>
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#aes-cmac">AES-CMAC</a></td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#aes-gcm">AES-GCM</a></td>
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#aes-cfb">AES-CFB</a></td>
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#aes-kw">AES-KW</a></td>
- <td></td>
- <td></td>
- <td />
- <td />
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#hmac">HMAC</a></td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td>✔</td>
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#dh">DH</a></td>
- <td />
- <td />
- <td />
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#sha">SHA-1</a></td>
- <td />
- <td />
- <td />
- <td />
- <td>✔</td>
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#sha">SHA-256</a></td>
- <td />
- <td />
- <td />
- <td />
- <td>✔</td>
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#sha">SHA-384</a></td>
- <td />
- <td />
- <td />
- <td />
- <td>✔</td>
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#sha">SHA-512</a></td>
- <td />
- <td />
- <td />
- <td />
- <td>✔</td>
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#concatkdf">CONCAT</a></td>
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#hkdf-ctr">HKDF-CTR</a></td>
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- <td />
- <td />
- </tr>
- <tr>
- <td><a href="#pbkdf2">PBKDF2</a></td>
- <td />
- <td />
- <td />
- <td />
- <td />
- <td />
- <td>✔</td>
- <td>✔</td>
- <td />
- <td />
- <td />
- <td />
+ <td>sign</td>
+ <td>None</td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>verify</td>
+ <td>None</td>
+ <td>boolean</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
</tr>
</tbody>
</table>
</div>
- <div id="recommended-algorithms" class="section">
- <h3>Recommended algorithms</h3>
- <p class="norm">This section is non-normative</p>
- <p>
- As the API is meant to be extensible in order to keep up with future developments within
- cryptography and to provide flexibility, there are no strictly required algorithms. Thus
- users of this API should check to see what algorithms are currently recommended and
- supported by implementations. As highlighted in the <a href="#security">Security
- Considerations</a>, even strong cryptographic algorithms may be combined in insecure
- ways. Users should therefore proceed with extreme caution when inventing new
- cryptographic protocols.
- </p>
- <p>
- Implementers should carefully review their support for different algorithms based on the
- evolving state of the cryptographic literature. It is expected that the set of
- widely-accepted algorithms will change over time as new advances are made.
- </p>
- <p>
- With the above caveats in mind, in order to promote interoperability for developers,
- this specification includes a list of suggested algorithms. These are considered to be
- the most widely used algorithms in practice at the time of writing, and therefore
- provide a good starting point for initial implementations of this specification. The
- suggested algorithms are:
- </p>
- <ul>
- <li>
- <a href="#hmac">HMAC</a> using <a href="#alg-sha-1">SHA-1</a>
- </li>
- <li>
- <a href="#hmac">HMAC</a> using <a href="#alg-sha-256">SHA-256</a>
- </li>
- <li>
- <a href="#rsassa-pkcs1">RSASSA-PKCS1-v1_5</a> using
- <a href="#alg-sha-256">SHA-1</a>
- </li>
- <li>
- <a href="#rsa-pss">RSA-PSS</a> using <a href="#alg-sha-256">SHA-256</a>
- and MGF1 with <a href="#alg-sha-256">SHA-256</a>.
- </li>
- <li>
- <a href="#rsa-oaep">RSA-OAEP</a> using <a href="#alg-sha-256">SHA-256</a>
- and MGF1 with <a href="#alg-sha-256">SHA-256</a>.
- </li>
- <li>
- <a href="#ecdsa">ECDSA</a> using <a href="#dfn-NamedCurve-p256">P-256</a>
- curve and <a href="#alg-sha-256">SHA-256</a>
- </li>
- <li><a href="#aes-cbc">AES-CBC</a></li>
- </ul>
- <p>
- To see the results of test-cases between implementations, please see the [@@Upcoming]
- Web Cryptography Test Cases Working Group.
- </p>
- </div>
- <div id="defining-an-algorithm" class="section">
- <h3>Defining an algorithm</h3>
- <p>
- Each algorithm that is to be exposed via the Web Cryptography API
- <span class="RFC2119">SHOULD</span> be registered via the Web Cryptography working group,
- and <span class="RFC2119">MUST</span> include all of the following details. Algorithms
- that are not registered via these means, but are exposed via this API,
- <span class="RFC2119">MUST</span> be processed as if the sections had been defined.
- </p>
- <div id="recognized-algorithm-name" class="section">
- <h4>Recognized algorithm name</h4>
- <p>
- Each registered algorithm <span class="RFC2119">MUST</span> have a canonical name
- for which applications can refer to the algorithm. The canonical name
- <span class="RFC2119">MUST</span> contain only ASCII characters and
- <span class="RFC2119">MUST NOT</span> equal any other canonical name or
- <a href="#dfn-algorithm-alias">algorithm alias</a> when every character in both names
- are converted to lower case.
- </p>
- </div>
- <div id="supported-operations" class="section">
- <h4>Supported operations</h4>
- <p>
- Each registered algorithm <span class="RFC2119">MUST</span> define the operations
- that it supports.
- </p>
- </div>
- <div id="algorithm-specific-params" class="section">
- <h4>Algorithm-specific parameters</h4>
- <p>
- Each registered algorithm <span class="RFC2119">MUST</span> define the expected
- parameters, if any, that should be exposed via the <a href="#dfn-Algorithm">Algorithm</a>
- dictionary for every <a href="#supported-operations">supported operation</a>.
- </p>
- </div>
- <div id="algorithm-result" class="section">
- <h4>Algorithm results</h4>
- <p>
- Each registered algorithm <span class="RFC2119">MUST</span> define the contents
- of the result of performing the underlying cryptographic operation for every
- <a href="#supported-operations">supported operation</a>.
- </p>
- </div>
- <div id="algorithm-alias" class="section">
- <h4><dfn id="dfn-algorithm-alias">Algorithm aliases</dfn></h4>
- <p>
- Each registered algorithm <span class="RFC2119">MAY</span> define one or more aliases
- that may define a fully normalized <a href="#dfn-Algorithm">Algorithm</a> object.
- </p>
- <p>
- Each algorithm alias <span class="RFC2119">MUST</span> follow the same naming rules
- as the <a href="#recognized-algorithm-name">recognized algorithm name</a>.
- </p>
- </div>
- </div>
-
- <div id="rsassa-pkcs1" class="section">
- <h3>RSASSA-PKCS1-v1_5</h3>
- <div id="rsassa-pkcs1-description" class="section">
- <h4>Description</h4>
- <p>
- The <code>"RSASSA-PKCS1-v1_5"</code> algorithm identifier is used to perform
- signing and verification using the RSASSA-PKCS1-v1_5 algorithm specified in
- [<cite><a href="#RFC3447">RFC3447</a></cite>].
- </p>
- </div>
- <div id="rsassa-pkcs1-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"RSASSA-PKCS1-v1_5"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>sign</td>
- <td>None</td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>verify</td>
- <td>None</td>
- <td>boolean</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="RsaHashedKeyGenParams-dictionary" class="section">
- <h4>RsaHashedKeyGenParams dictionary</h4>
- <x:codeblock language="idl">
+ <div id="RsaHashedKeyGenParams-dictionary" class="section">
+ <h4>RsaHashedKeyGenParams dictionary</h4>
+ <x:codeblock language="idl">
dictionary <dfn id="dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</dfn> : <a href="#dfn-RsaKeyGenParams">RsaKeyGenParams</a> {
- <span class="comment">// The hash algorithm to use</span>
- <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> <dfn id="dfn-RsaHashedKeyGenParams-hash">hash</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="RsaHashedKeyAlgorithm-dictionary" class="section">
- <h4>RsaHashedKeyAlgorithm dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</dfn> : <a href="#dfn-RsaKeyAlgorithm">RsaKeyAlgorithm</a> {
- <span class="comment">// The hash algorithm that is used with this key</span>
- <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> <dfn id="dfn-RsaHashedKeyAlgorithm-hash">hash</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="RsaHashedImportParams-dictionary" class="section">
- <h4>RsaHashedImportParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-RsaHashedImportParams">RsaHashedImportParams</dfn> {
- <span class="comment">// The hash algorithm to use</span>
- <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> <dfn id="dfn-RsaHashedImportParams-hash">hash</dfn>;
+<span class="comment">// The hash algorithm to use</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-RsaHashedKeyGenParams-hash">hash</dfn>;
};
- </x:codeblock>
- <div class="ednote">
- <p>
- Should this be folded into RsaHashedKeyGenParams and rely on the optional nature of the
- dictionary fields?
- </p>
- </div>
- </div>
- <div id="rsassa-pkcs1-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Sign</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the signature generation operation defined in Section 8.2 of [<cite><a
- href="#RFC3447">RFC3447</a></cite>] with the key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- as the signer's private key and the <a
- href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
- <var>M</var> and using the hash function specified in the <a
- href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>signature</var> be the value <var>S</var> that results from
- performing the operation.
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Verify</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the signature verification operation defined in Section 8.2 of
- [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the
- [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> as the signer's RSA public key and the <a
- href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
- <var>M</var> and the <a href="#concept-contents-of-arraybuffer">contents of
- <var>signature</var></a> as <var>S</var> and using the hash function specified
- in the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
- [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a boolean with value true if the
- result of the operations was "valid signature" and a boolean with value
- false otherwise.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a> are not present
- in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an RSA key pair, as defined in [<cite><a
- href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> attribute of
- <var>normalizedAlgorithm</var> and RSA public exponent equal to the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> attribute of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If generation of the key pair fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSASSA-PKCS1-v1_5"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
- attribute of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
- attribute of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
- of <var>algorithm</var> to equal the
- <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the <a href="#concept-usage-intersection">usage
- intersection</a> of <var>usages</var> and <code>[ "verify" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
- intersection</a> of <var>usages</var> and <code>[ "sign" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to be <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to be <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object, as
- defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- <div class="ednote">
- <p>
- TODO: Specify the mapping between key.algorithm.hash and the appropriate Hash
- functions (and back to OID).
- </p>
- </div>
- </dd>
-
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>Let <var>keyData</var> be the key data to be imported.</p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#concept-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a
- href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a> are not present in
- <var>normalizedAlgorithm</var> then <a href="#concept-return-an-error">return
- an error</a> named <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the
- <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>algorithm</code> AlgorithmIdentifier field of
- <var>spki</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in Section 2.3.1 of <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha1WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha256WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha384WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha512WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be the result of performing the <a
- href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
- <var>structure</var> as the <code>RSAPublicKey</code> structure
- specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA public key identified by
- <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>privateKeyAlgorithm</code>
- PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in Section 2.3.1 of <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha1WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha256WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha384WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha512WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>rsaPrivateKey</var> be the result of performing the <a
- href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>privateKey</code> field of <var>privateKeyInfo</var>,
- <var>structure</var> as the <code>RSAPrivateKey</code> structure
- specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA private key identified by
- <var>rsaPrivateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not a
- case-sensitive string match to <code>"RSA"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not a case-sensitive string match to <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is not
- present:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"RS1"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"RS256"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"RS384"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"RS512"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.3.2 of <a href="#jwa">JSON Web
- Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a
- href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA private key identified by interpreting <var>jwk</var>
- according to Section 6.3.2 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a
- href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA public key identified by interpreting <var>jwk</var>
- according to Section 6.3.1 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a> dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSASSA-PKCS1-v1_5"</code>
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to the length, in bits, of the RSA public
- modulus.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
- representation of the RSA public exponent.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
- <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
- whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>Return <var>key</var>.</p>
- </li>
- </ol>
- </dd>
-
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>key</var> be the key to be exported.
- </p>
- </li>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code></dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a
- href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>1.2.840.113549.1.1</code>
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to the ASN.1 type NULL.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> field to the result of
- DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
- in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
- represents the RSA public key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a
- href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
- with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>version</var> field to 0.
- </p>
- </li>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to a
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>1.2.840.113549.1.1</code>
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to the ASN.1 type NULL.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to the result of DER-encoding
- an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a
- href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
- RSA private key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- <div class="ednote">
- <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
- this field should be <em>BER</em> encoded in Section 5 (as a "for
- example"). However, to avoid requiring WebCrypto implementations
- support BER-encoding and BER-decoding, only <em>DER</em> encodings
- are produced or accepted.
- </div>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ul>
- <li>
- <p>Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.</p>
- </li>
- <li>
- <p>Set the <code>kty</code> attribute of <var>jwk</var> to the string
- <code>"RSA"</code>.</p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
- attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>hash</var> is <code>SHA-1</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>RS1</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-256</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>RS256</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-384</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>RS384</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-512</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>RS512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>RSA1_5</code>.</p>
- </li>
- <li>
- <p>
- Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
- according to the corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.1.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>"private"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Set the attributes named <code>d</code>, <code>p</code>,
- <code>q</code>, <code>dp</code>, <code>dq</code>, and
- <code>qi</code> of <var>jwk</var> according to the
- corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.2.
- </p>
- </li>
- <li>
- <p>
- If the underlying RSA private key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var> is represented by more than two primes, set
- the attribute named <code>oth</code> of <var>jwk</var>
- according to the corresponding definition in <a
- href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a
- href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ul>
- </dd>
- <dt>Otherwise</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="rsa-pss" class="section">
- <h3>RSA-PSS</h3>
- <div id="rsa-pss-description" class="section">
- <h4>Description</h4>
+ </x:codeblock>
+ </div>
+ <div id="RsaHashedKeyAlgorithm-dictionary" class="section">
+ <h4>RsaHashedKeyAlgorithm dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</dfn> : <a href="#dfn-RsaKeyAlgorithm">RsaKeyAlgorithm</a> {
+<span class="comment">// The hash algorithm that is used with this key</span>
+<a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> <dfn id="dfn-RsaHashedKeyAlgorithm-hash">hash</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="RsaHashedImportParams-dictionary" class="section">
+ <h4>RsaHashedImportParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-RsaHashedImportParams">RsaHashedImportParams</dfn> {
+<span class="comment">// The hash algorithm to use</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-RsaHashedImportParams-hash">hash</dfn>;
+};
+ </x:codeblock>
+ <div class="ednote">
<p>
- The <code>"RSA-PSS"</code> algorithm identifier is used to perform signing
- and verification using the RSASSA-PSS algorithm specified in
- [<cite><a href="#RFC3447">RFC3447</a></cite>], using the mask generation
- formula MGF1.
+ Should this be folded into RsaHashedKeyGenParams and rely on the optional nature of the
+ dictionary fields?
</p>
</div>
- <div id="rsa-pss-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"RSA-PSS"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>sign</td>
- <td><a href="#dfn-RsaPssParams">RsaPssParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>verify</td>
- <td><a href="#dfn-RsaPssParams">RsaPssParams</a></td>
- <td>boolean</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="RsaPssParams-dictionary" class="section">
- <h4>RsaPssParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-RsaPssParams">RsaPssParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The desired length of the random salt</span>
- [EnforceRange] unsigned long <dfn id="dfn-RsaPssParams-saltLength">saltLength</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="rsa-pss-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Sign</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaPssParams">RsaPssParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaPssParams">RsaPssParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the signature generation operation defined in Section 8.1 of [<cite><a
- href="#RFC3447">RFC3447</a></cite>] with the key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- as the signer's private key, <var>K</var>, and the <a
- href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
- the message to be signed, <var>M</var>, and using the hash function specified
- by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
- [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option, MGF1 (defined in Section B.2.1 of [<cite><a
- href="#RFC3447">RFC3447</a></cite>]) as the MGF option and the <a
- href="#dfn-RsaPssParams-saltLength">saltLength</a> member of
- <var>normalizedAlgorithm</var> as the salt length option for the
- EMM-PSS-ENCODE operation.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>signature</var> be a new <code>ArrayBuffer</code> containing the
- signature, S, that results from performing the operation.
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Verify</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaPssParams">RsaPssParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaPssParams">RsaPssParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the signature verification operation defined in Section 8.1 of
- [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the
- [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> as the signer's RSA public key and the <a
- href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
- <var>M</var> and <a href="#concept-contents-of-arraybuffer">the contents of
- <var>signature</var></a> as <var>S</var> and using the hash function specified
- by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
- [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option, MGF1 (defined in Section B.2.1 of [<cite><a
- href="#RFC3447">RFC3447</a></cite>]) as the MGF option and the <a
- href="#dfn-RsaPssParams-saltLength">saltLength</a> member of
- <var>normalizedAlgorithm</var> as the salt length option for the
- EMSA-PSS-VERIFY operation.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a boolean with value true if the
- result of the operation was "valid signature" and a boolean with value
- false otherwise.
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a> are not present
- in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an RSA key pair, as defined in [<cite><a
- href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> member of
- <var>normalizedAlgorithm</var> and RSA public exponent equal to the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSA-PSS"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
- of <var>algorithm</var> to equal the
- <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the <a href="#concept-usage-intersection">usage
- intersection</a> of <var>usages</var> and <code>[ "verify" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
- intersection</a> of <var>usages</var> and <code>[ "sign" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object,
- as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>Let <var>keyData</var> be the key data to be imported.</p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#concept-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a
- href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a> are not present in
- <var>normalizedAlgorithm</var> then <a href="#concept-return-an-error">return
- an error</a> named <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the
- <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>algorithm</code> AlgorithmIdentifier field of
- <var>spki</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>id-RSASSA-PSS</code> OID defined in
- <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>params</var> be the ASN.1 structure contained within
- the <code>parameters</code> field of the <code>algorithm</code>
- AlgorithmIdentifier field of <var>spki</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not defined, or is not an instance of
- the <code>RSASSA-PSS-params</code> ASN.1 type defined in
- <a href="#RFC3447">RFC3447</a>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
- within the <code>hashAlgorithm</code> field of <var>params</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- equivalent to the OID <code>id-mgf1</code> defined in <a
- href="#RFC3447">RFC 3447</a>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- an instance of the <code>HashAlgorithm</code> ASN.1 type that is
- identical in content to the <code>hashAlglorithm</code> field of
- <var>params</var>, <a href="#concept-return-an-error">return an
- error</a> named <a
- href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be the result of performing the <a
- href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
- <var>structure</var> as the <code>RSAPublicKey</code> structure
- specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA public key identified by
- <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>privateKeyAlgorithm</code>
- PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the <code>id-RSASSA-PSS</code> OID
- defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>params</var> be the ASN.1 structure contained within
- the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier
- field of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not defined, or is not an instance of
- the <code>RSASSA-PSS-params</code> ASN.1 type defined in
- <a href="#RFC3447">RFC3447</a>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
- within the <code>hashAlgorithm</code> field of <var>params</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- equivalent to the OID <code>id-mgf1</code> defined in <a
- href="#RFC3447">RFC 3447</a>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- an instance of the <code>HashAlgorithm</code> ASN.1 type that is
- identical in content to the <code>hashAlglorithm</code> field of
- <var>params</var>, <a href="#concept-return-an-error">return an
- error</a> named <a
- href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>rsaPrivateKey</var> be the result of performing the <a
- href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>privateKey</code> field of <var>privateKeyInfo</var>,
- <var>structure</var> as the <code>RSAPrivateKey</code> structure
- specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA private key identified by
- <var>rsaPrivateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not a
- case-sensitive string match to <code>"RSA"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not a case-sensitive string match to <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is not
- present:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"PS1"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"PS256"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"PS384"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"PS512"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.3.2 of <a href="#jwa">JSON Web
- Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a
- href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA private key identified by interpreting <var>jwk</var>
- according to Section 6.3.2 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a
- href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA public key identified by interpreting <var>jwk</var>
- according to Section 6.3.1 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
+ </div>
+ <div id="rsassa-pkcs1-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Sign</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the signature generation operation defined in Section 8.2 of [<cite><a
+ href="#RFC3447">RFC3447</a></cite>] with the key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ as the signer's private key and the <a
+ href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
+ <var>M</var> and using the hash function specified in the <a
+ href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>signature</var> be the value <var>S</var> that results from
+ performing the operation.
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Verify</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the signature verification operation defined in Section 8.2 of
+ [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the
+ [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> as the signer's RSA public key and the <a
+ href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
+ <var>M</var> and the <a href="#concept-contents-of-arraybuffer">contents of
+ <var>signature</var></a> as <var>S</var> and using the hash function specified
+ in the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
+ [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a boolean with value true if the
+ result of the operations was "valid signature" and a boolean with value
+ false otherwise.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an RSA key pair, as defined in [<cite><a
+ href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> attribute of
+ <var>normalizedAlgorithm</var> and RSA public exponent equal to the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> attribute of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If generation of the key pair fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSASSA-PKCS1-v1_5"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
+ attribute of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
+ attribute of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
+ of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the <a href="#concept-usage-intersection">usage
+ intersection</a> of <var>usages</var> and <code>[ "verify" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
+ intersection</a> of <var>usages</var> and <code>[ "sign" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to be <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to be <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object, as
+ defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ <div class="ednote">
+ <p>
+ TODO: Specify the mapping between key.algorithm.hash and the appropriate Hash
+ functions (and back to OID).
+ </p>
+ </div>
+ </dd>
+
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>Let <var>keyData</var> be the key data to be imported.</p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the
+ <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>algorithm</code> AlgorithmIdentifier field of
+ <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in Section 2.3.1 of <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha1WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha256WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha384WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha512WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be the result of performing the <a
+ href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
+ <var>structure</var> as the <code>RSAPublicKey</code> structure
+ specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA public key identified by
+ <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>privateKeyAlgorithm</code>
+ PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in Section 2.3.1 of <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha1WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha256WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha384WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha512WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>rsaPrivateKey</var> be the result of performing the <a
+ href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>privateKey</code> field of <var>privateKeyInfo</var>,
+ <var>structure</var> as the <code>RSAPrivateKey</code> structure
+ specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA private key identified by
+ <var>rsaPrivateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not a
+ case-sensitive string match to <code>"RSA"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not a case-sensitive string match to <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is not
+ present:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"RS1"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"RS256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"RS384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"RS512"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.3.2 of <a href="#jwa">JSON Web
+ Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a
+ href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA private key identified by interpreting <var>jwk</var>
+ according to Section 6.3.2 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a
+ href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA public key identified by interpreting <var>jwk</var>
+ according to Section 6.3.1 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a> dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSASSA-PKCS1-v1_5"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to the length, in bits, of the RSA public
+ modulus.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
+ representation of the RSA public exponent.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
+ <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>Return <var>key</var>.</p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>key</var> be the key to be exported.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code></dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a
+ href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>1.2.840.113549.1.1</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to the ASN.1 type NULL.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> field to the result of
+ DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
+ in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
+ represents the RSA public key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a
+ href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
+ with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>version</var> field to 0.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to a
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>1.2.840.113549.1.1</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to the ASN.1 type NULL.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to the result of DER-encoding
+ an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a
+ href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
+ RSA private key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ <div class="ednote">
+ <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
+ this field should be <em>BER</em> encoded in Section 5 (as a "for
+ example"). However, to avoid requiring WebCrypto implementations
+ support BER-encoding and BER-decoding, only <em>DER</em> encodings
+ are produced or accepted.
+ </div>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ul>
+ <li>
+ <p>Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.</p>
+ </li>
+ <li>
+ <p>Set the <code>kty</code> attribute of <var>jwk</var> to the string
+ <code>"RSA"</code>.</p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
+ attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>hash</var> is <code>SHA-1</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>RS1</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-256</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>RS256</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-384</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>RS384</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-512</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>RS512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>RSA1_5</code>.</p>
+ </li>
+ <li>
+ <p>
+ Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
+ according to the corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.1.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is <code>"private"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Set the attributes named <code>d</code>, <code>p</code>,
+ <code>q</code>, <code>dp</code>, <code>dq</code>, and
+ <code>qi</code> of <var>jwk</var> according to the
+ corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.2.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying RSA private key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var> is represented by more than two primes, set
+ the attribute named <code>oth</code> of <var>jwk</var>
+ according to the corresponding definition in <a
+ href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a
+ href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ul>
+ </dd>
+ <dt>Otherwise</dt>
+ <dd>
+ <p>
<a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a> dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSA-PSS"</code>
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to the length, in bits, of the RSA public
- modulus.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
- representation of the RSA public exponent.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
- <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
- whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>
- </p>
- </li>
- <li>
- <p>Return <var>key</var>.</p>
- </li>
- </ol>
- </dd>
-
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>key</var> be the key to be exported.
- </p>
- </li>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code></dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a
- href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-RSASSA-PSS</code> defined in
- <a href="#RFC3447">RFC 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>RSASSA-PSS-params</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>hashAlgorithm</var> field to an instance of
- the <code>HashAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-1</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha1</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-256</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha256</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-384</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha384</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-512</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha512</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <var>maskGenAlgorithm</var> field to an instance
- of the <code>MaskGenAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
- 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>HashAlgorithm</code> ASN.1 type that is
- identical to the <var>hashAlgorithm</var> field.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>saltLength</var> field to the length in
- octets of the digest algorithm identified by the <a
- href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
- of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> field to the result of
- DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
- in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
- represents the RSA public key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a
- href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
- with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>version</var> field to 0.
- </p>
- </li>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to an
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-RSASSA-PSS</code> defined in
- <a href="#RFC3447">RFC 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>RSASSA-PSS-params</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>hashAlgorithm</var> field to an instance of
- the <code>HashAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-1</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha1</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-256</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha256</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-384</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha384</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-512</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha512</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <var>maskGenAlgorithm</var> field to an instance
- of the <code>MaskGenAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
- 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>HashAlgorithm</code> ASN.1 type that is
- identical to the <var>hashAlgorithm</var> field.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>saltLength</var> field to the length in
- octets of the digest algorithm identified by the <a
- href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
- of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to the result of DER-encoding
- an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a
- href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
- RSA private key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- <div class="ednote">
- <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
- this field should be <em>BER</em> encoded in Section 5 (as a "for
- example"). However, to avoid requiring WebCrypto implementations
- support BER-encoding and BER-decoding, only <em>DER</em> encodings
- are produced or accepted.
- </div>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ul>
- <li>
- <p>Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a> dictionary.</p>
- </li>
- <li>
- <p>Set the <code>kty</code> attribute of <var>jwk</var> to the string
- <code>"RSA"</code>.</p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>hash</var> is <code>SHA-1</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>PS1</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-256</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>PS256</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-384</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>PS384</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-512</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>PS512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
- according to the corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.1.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is <code>"private"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Set the attributes named <code>d</code>, <code>p</code>,
- <code>q</code>, <code>dp</code>, <code>dq</code>, and
- <code>qi</code> of <var>jwk</var> according to the
- corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.2.
- </p>
- </li>
- <li>
- <p>
- If the underlying RSA private key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var> is represented by more than two primes, set
- the attribute named <code>oth</code> of <var>jwk</var>
- according to the corresponding definition in <a
- href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a
- href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ul>
- </dd>
- <dt>Otherwise</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="rsa-oaep" class="section">
- <h3>RSA-OAEP</h3>
- <div id="rsa-oaep-description" class="section">
- <h4>Description</h4>
- <p>
- The <code>"RSA-OAEP"</code> algorithm identifier is used to perform encryption
- and decryption ordering to the RSAES-OAEP algorithm specified in
- [<cite><a href="#RFC3447">RFC3447</a></cite>], using the mask
- generation function MGF1.
- </p>
- </div>
- <div id="rsa-oaep-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"RSA-OAEP"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>encrypt</td>
- <td><a href="#dfn-RsaOaepParams">RsaOaepParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>decrypt</td>
- <td><a href="#dfn-RsaOaepParams">RsaOaepParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- </tbody>
- </table>
- </div>
-
- <div id="rsa-oaep-params" class="section">
- <h4>RsaOaepParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-RsaOaepParams">RsaOaepParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The optional label/application data to associate with the message</span>
- CryptoOperationData? <dfn id="dfn-RsaOaepParams-label">label</dfn>;
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="rsa-pss" class="section">
+ <h3>RSA-PSS</h3>
+ <div id="rsa-pss-description" class="section">
+ <h4>Description</h4>
+ <p>
+ The <code>"RSA-PSS"</code> algorithm identifier is used to perform signing
+ and verification using the RSASSA-PSS algorithm specified in
+ [<cite><a href="#RFC3447">RFC3447</a></cite>], using the mask generation
+ formula MGF1.
+ </p>
+ </div>
+ <div id="rsa-pss-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"RSA-PSS"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sign</td>
+ <td><a href="#dfn-RsaPssParams">RsaPssParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>verify</td>
+ <td><a href="#dfn-RsaPssParams">RsaPssParams</a></td>
+ <td>boolean</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="RsaPssParams-dictionary" class="section">
+ <h4>RsaPssParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-RsaPssParams">RsaPssParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The desired length of the random salt</span>
+[EnforceRange] unsigned long <dfn id="dfn-RsaPssParams-saltLength">saltLength</dfn>;
};
- </x:codeblock>
- </div>
- <div id="rsa-oaep-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Encrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of <var>key</var>
- is not <code>"public"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaOaepParams">RsaOaepParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaOaepParams">RsaOaepParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the encryption operation defined in Section 7.1 of [<cite><a
- href="#RFC3447">RFC3447</a></cite>] with the key represented by <var>key</var>
- as the recipient's RSA public key, the <a
- href="#concept-contents-of-arraybuffer">contents of <var>plaintext</var></a>
- as the message to be encrypted, <var>M</var> and the <a
- href="#concept-contents-of-arraybuffer">contents of</a> <a
- href="#dfn-RsaOaepParams-label">label</a> member of
- <var>normalizedAlgorithm</var> as the label, <var>L</var>, and with the hash
- function specified by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option and MGF1 (defined in Section B.2.1 of
- [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ciphertext</var> be a new <code>ArrayBuffer</code>
- containing the value <var>C</var> that results from performing the
- operation.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Decrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of <var>key</var>
- is not <code>"private"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaOaepParams">RsaOaepParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaOaepParams">RsaOaepParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the decryption operation defined in Section 7.1 of [<cite><a
- href="#RFC3447">RFC3447</a></cite>] with the key represented by <var>key</var>
- as the recipient's RSA private key, the <a
- href="#concept-contents-of-arraybuffer">contents of <var>ciphertext</var></a>
- as the ciphertext to be decrypted, C, and the <a
- href="#concept-contents-of-arraybuffer">contents of</a> the <a
- href="#dfn-RsaOaepParams-label">label</a> member of
- <var>normalizedAlgorithm</var> as the label, <var>L</var>, and with the hash
- function specified by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option and MGF1 (defined in Section B.2.1 of
- [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>plaintext</var> be a new <code>ArrayBuffer</code>
- containing the value <var>M</var> that results from performing the
- operation.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a> are not present
- in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- <code>"encrypt"</code>, <code>"decrypt</code>,
- <code>wrapKey</code> or <code>unwrapKey</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an RSA key pair, as defined in [<cite><a
- href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> member of
- <var>normalizedAlgorithm</var> and RSA public exponent equal to the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSA-OAEP"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
- of <var>algorithm</var> to equal the
- <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot of
- <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the
- <a href="#concept-usage-intersection">usage intersection</a> of
- <var>usages</var> and <code>[ "encrypt", "wrapKey" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot of
- <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be the
- <a href="#concept-usage-intersection">usage intersection</a> of
- <var>usages</var> and <code>[ "decrypt", "unwrapKey" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to be <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to be <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object, as
- defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>Let <var>keyData</var> be the key data to be imported.</p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#concept-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a
- href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a> are not present in
- <var>normalizedAlgorithm</var> then <a href="#concept-return-an-error">return
- an error</a> named <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the
- <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>algorithm</code> AlgorithmIdentifier field of
- <var>spki</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the <code>id-RSAES-OAEP</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>params</var> be the ASN.1 structure contained within
- the <code>parameters</code> field of the <code>algorithm</code>
- AlgorithmIdentifier field of <var>spki</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not defined, or is not an instance of
- the <code>RSAES-OAEP-params</code> ASN.1 type defined in
- <a href="#RFC3447">RFC3447</a>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
- within the <code>hashAlgorithm</code> field of <var>params</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- equivalent to the OID <code>id-mgf1</code> defined in <a
- href="#RFC3447">RFC 3447</a>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- an instance of the <code>HashAlgorithm</code> ASN.1 type that is
- identical in content to the <code>hashAlglorithm</code> field of
- <var>params</var>, <a href="#concept-return-an-error">return an
- error</a> named <a
- href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be the result of performing the <a
- href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
- <var>structure</var> as the <code>RSAPublicKey</code> structure
- specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA public key identified by
- <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>privateKeyAlgorithm</code>
- PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the <code>id-RSAES-OAEP</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>params</var> be the ASN.1 structure contained within
- the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier
- field of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not defined, or is not an instance of
- the <code>RSAES-OAEP-params</code> ASN.1 type defined in <a
- href="#RFC3447">RFC3447</a>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
- within the <code>hashAlgorithm</code> field of
- <var>params</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the
- <code>id-sha256</code> OID defined in <a href="#RFC3447">RFC
- 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the
- <code>id-sha384</code> OID defined in <a href="#RFC3447">RFC
- 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the
- <code>id-sha512</code> OID defined in <a href="#RFC3447">RFC
- 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- equivalent to the OID <code>id-mgf1</code> defined in <a
- href="#RFC3447">RFC 3447</a>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- an instance of the <code>HashAlgorithm</code> ASN.1 type that is
- identical in content to the <code>hashAlglorithm</code> field of
- <var>params</var>, <a href="#concept-return-an-error">return an
- error</a> named <a
- href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>rsaPrivateKey</var> be the result of performing the <a
- href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>privateKey</code> field of <var>privateKeyInfo</var>,
- <var>structure</var> as the <code>RSAPrivateKey</code> structure
- specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA private key identified by
- <var>rsaPrivateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not a
- case-sensitive string match to <code>"RSA"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not a case-sensitive string match to <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>alg</code> field of <var>jwk</var> is not present:</dt>
- <dd>Let <var>hash</var> be undefined.</dd>
- <dt>
- If the <code>alg</code> field of <var>jwk</var> is equal to
- <code>RSA-OAEP</code>:
- </dt>
- <dd>Let <var>hash</var> be the string <code>SHA-1</code>.</dd>
- <dt>
- If the <code>alg</code> field of <var>jwk</var> is equal to
- <code>RSA-OAEP-256</code>:
- </dt>
- <dd>Let <var>hash</var> be the string <code>SHA-256</code>.</dd>
- <dt>
- If the <code>alg</code> field of <var>jwk</var> is equal to
- <code>RSA-OAEP-384</code>:
- </dt>
- <dd>Let <var>hash</var> be the string <code>SHA-384</code>.</dd>
- <dt>
- If the <code>alg</code> field of <var>jwk</var> is equal to
- <code>RSA-OAEP-512</code>:
- </dt>
- <dd>Let <var>hash</var> be the string <code>SHA-512</code>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">return an error</a> named
+ </x:codeblock>
+ </div>
+ <div id="rsa-pss-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Sign</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the signature generation operation defined in Section 8.1 of [<cite><a
+ href="#RFC3447">RFC3447</a></cite>] with the key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ as the signer's private key, <var>K</var>, and the <a
+ href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
+ the message to be signed, <var>M</var>, and using the hash function specified
+ by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
+ [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option, MGF1 (defined in Section B.2.1 of [<cite><a
+ href="#RFC3447">RFC3447</a></cite>]) as the MGF option and the <a
+ href="#dfn-RsaPssParams-saltLength">saltLength</a> member of
+ <var>normalizedAlgorithm</var> as the salt length option for the
+ EMM-PSS-ENCODE operation.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>signature</var> be a new <code>ArrayBuffer</code> containing the
+ signature, S, that results from performing the operation.
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Verify</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the signature verification operation defined in Section 8.1 of
+ [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the
+ [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> as the signer's RSA public key and the <a
+ href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
+ <var>M</var> and <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>signature</var></a> as <var>S</var> and using the hash function specified
+ by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
+ [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option, MGF1 (defined in Section B.2.1 of [<cite><a
+ href="#RFC3447">RFC3447</a></cite>]) as the MGF option and the <a
+ href="#dfn-RsaPssParams-saltLength">saltLength</a> member of
+ <var>normalizedAlgorithm</var> as the salt length option for the
+ EMSA-PSS-VERIFY operation.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a boolean with value true if the
+ result of the operation was "valid signature" and a boolean with value
+ false otherwise.
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an RSA key pair, as defined in [<cite><a
+ href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> member of
+ <var>normalizedAlgorithm</var> and RSA public exponent equal to the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSA-PSS"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
+ of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the <a href="#concept-usage-intersection">usage
+ intersection</a> of <var>usages</var> and <code>[ "verify" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
+ intersection</a> of <var>usages</var> and <code>[ "sign" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object,
+ as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>Let <var>keyData</var> be the key data to be imported.</p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the
+ <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>algorithm</code> AlgorithmIdentifier field of
+ <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>id-RSASSA-PSS</code> OID defined in
+ <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>params</var> be the ASN.1 structure contained within
+ the <code>parameters</code> field of the <code>algorithm</code>
+ AlgorithmIdentifier field of <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not defined, or is not an instance of
+ the <code>RSASSA-PSS-params</code> ASN.1 type defined in
+ <a href="#RFC3447">RFC3447</a>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
+ within the <code>hashAlgorithm</code> field of <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ equivalent to the OID <code>id-mgf1</code> defined in <a
+ href="#RFC3447">RFC 3447</a>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ an instance of the <code>HashAlgorithm</code> ASN.1 type that is
+ identical in content to the <code>hashAlglorithm</code> field of
+ <var>params</var>, <a href="#concept-return-an-error">return an
+ error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a
- href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
- href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.3.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a
- href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA private key identified by interpreting <var>jwk</var>
- according to Section 6.3.2 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a
- href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA public key identified by interpreting <var>jwk</var>
- according to Section 6.3.1 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be the result of performing the <a
+ href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
+ <var>structure</var> as the <code>RSAPublicKey</code> structure
+ specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA public key identified by
+ <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>privateKeyAlgorithm</code>
+ PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the <code>id-RSASSA-PSS</code> OID
+ defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>params</var> be the ASN.1 structure contained within
+ the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier
+ field of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not defined, or is not an instance of
+ the <code>RSASSA-PSS-params</code> ASN.1 type defined in
+ <a href="#RFC3447">RFC3447</a>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
+ within the <code>hashAlgorithm</code> field of <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ equivalent to the OID <code>id-mgf1</code> defined in <a
+ href="#RFC3447">RFC 3447</a>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ an instance of the <code>HashAlgorithm</code> ASN.1 type that is
+ identical in content to the <code>hashAlglorithm</code> field of
+ <var>params</var>, <a href="#concept-return-an-error">return an
+ error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>rsaPrivateKey</var> be the result of performing the <a
+ href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>privateKey</code> field of <var>privateKeyInfo</var>,
+ <var>structure</var> as the <code>RSAPrivateKey</code> structure
+ specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA private key identified by
+ <var>rsaPrivateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not a
+ case-sensitive string match to <code>"RSA"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not a case-sensitive string match to <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is not
+ present:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"PS1"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"PS256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"PS384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"PS512"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.3.2 of <a href="#jwa">JSON Web
+ Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a
+ href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA private key identified by interpreting <var>jwk</var>
+ according to Section 6.3.2 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a
+ href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA public key identified by interpreting <var>jwk</var>
+ according to Section 6.3.1 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a> dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSA-PSS"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to the length, in bits, of the RSA public
+ modulus.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
+ representation of the RSA public exponent.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
+ <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>
+ </p>
+ </li>
+ <li>
+ <p>Return <var>key</var>.</p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>key</var> be the key to be exported.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code></dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a
+ href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-RSASSA-PSS</code> defined in
+ <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>RSASSA-PSS-params</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>hashAlgorithm</var> field to an instance of
+ the <code>HashAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-1</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha1</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-256</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha256</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-384</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha384</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-512</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha512</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <var>maskGenAlgorithm</var> field to an instance
+ of the <code>MaskGenAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
+ 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>HashAlgorithm</code> ASN.1 type that is
+ identical to the <var>hashAlgorithm</var> field.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>saltLength</var> field to the length in
+ octets of the digest algorithm identified by the <a
+ href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
+ of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> field to the result of
+ DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
+ in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
+ represents the RSA public key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a
+ href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
+ with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>version</var> field to 0.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to an
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-RSASSA-PSS</code> defined in
+ <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>RSASSA-PSS-params</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>hashAlgorithm</var> field to an instance of
+ the <code>HashAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-1</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha1</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-256</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha256</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-384</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha384</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-512</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha512</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <var>maskGenAlgorithm</var> field to an instance
+ of the <code>MaskGenAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
+ 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>HashAlgorithm</code> ASN.1 type that is
+ identical to the <var>hashAlgorithm</var> field.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>saltLength</var> field to the length in
+ octets of the digest algorithm identified by the <a
+ href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
+ of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to the result of DER-encoding
+ an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a
+ href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
+ RSA private key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ <div class="ednote">
+ <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
+ this field should be <em>BER</em> encoded in Section 5 (as a "for
+ example"). However, to avoid requiring WebCrypto implementations
+ support BER-encoding and BER-decoding, only <em>DER</em> encodings
+ are produced or accepted.
+ </div>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ul>
+ <li>
+ <p>Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a> dictionary.</p>
+ </li>
+ <li>
+ <p>Set the <code>kty</code> attribute of <var>jwk</var> to the string
+ <code>"RSA"</code>.</p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>hash</var> is <code>SHA-1</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>PS1</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-256</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>PS256</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-384</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>PS384</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-512</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>PS512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
+ according to the corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.1.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is <code>"private"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Set the attributes named <code>d</code>, <code>p</code>,
+ <code>q</code>, <code>dp</code>, <code>dq</code>, and
+ <code>qi</code> of <var>jwk</var> according to the
+ corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.2.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying RSA private key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var> is represented by more than two primes, set
+ the attribute named <code>oth</code> of <var>jwk</var>
+ according to the corresponding definition in <a
+ href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a
+ href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ul>
+ </dd>
+ <dt>Otherwise</dt>
+ <dd>
+ <p>
<a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSA-OAEP"</code>
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to the length, in bits, of the RSA public
- modulus.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
- representation of the RSA public exponent.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
- <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
- whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> to <var>algorithm</var>
- </p>
- </li>
- <li>
- <p>Return <var>key</var>.</p>
- </li>
- </ol>
- </dd>
-
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>key</var> be the key to be exported.
- </p>
- </li>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code></dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a
- href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-RSAES-OAEP</code> defined in
- <a href="#RFC3447">RFC 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>RSAES-OAEP-params</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>hashAlgorithm</var> field to an instance of
- the <code>HashAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-1</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha1</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-256</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha256</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-384</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha384</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-512</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha512</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <var>maskGenAlgorithm</var> field to an instance
- of the <code>MaskGenAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
- 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>HashAlgorithm</code> ASN.1 type that is
- identical to the <var>hashAlgorithm</var> field.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> field to the result of
- DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
- in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
- represents the RSA public key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a
- href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
- with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>version</var> field to 0.
- </p>
- </li>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to an
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-RSAES-OAEP</code> defined in
- <a href="#RFC3447">RFC 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>RSAES-OAEP-params</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>hashAlgorithm</var> field to an instance of
- the <code>HashAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-1</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha1</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-256</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha256</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-384</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha384</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-512</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha512</code> defined in <a
- href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <var>maskGenAlgorithm</var> field to an instance
- of the <code>MaskGenAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
- 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>HashAlgorithm</code> ASN.1 type that is
- identical to the <var>hashAlgorithm</var> field.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to the result of DER-encoding
- an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a
- href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
- RSA private key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- <div class="ednote">
- <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
- this field should be <em>BER</em> encoded in Section 5 (as a "for
- example"). However, to avoid requiring WebCrypto implementations
- support BER-encoding and BER-decoding, only <em>DER</em> encodings
- are produced or accepted.
- </div>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ul>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the string
- <code>"RSA"</code>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>SHA-1</code>:
- </dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>"RSA-OAEP"</code>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>SHA-256</code>:
- </dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>"RSA-OAEP-256"</code>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>SHA-384</code>:
- </dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>"RSA-OAEP-384"</code>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
- href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>SHA-512</code>:
- </dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>"RSA-OAEP-512"</code>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
- according to the corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.1.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>"private"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Set the attributes named <code>d</code>, <code>p</code>,
- <code>q</code>, <code>dp</code>, <code>dq</code>, and
- <code>qi</code> of <var>jwk</var> according to the
- corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.2.
- </p>
- </li>
- <li>
- <p>
- If the underlying RSA private key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var> is represented by more than two primes, set
- the attribute named <code>oth</code> of <var>jwk</var>
- according to the corresponding definition in <a
- href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a
- href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ul>
- </dd>
- <dt>Otherwise</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="ecdsa" class="section">
- <h3>ECDSA</h3>
- <div id="ecdsa-description" class="section">
- <h4>Description</h4>
- <p>
- The <code>"ECDSA"</code> algorithm identifier is used to perform signing
- and verification using the ECDSA algorithm specified in
- [<cite><a href="#X9.62">X9.62</a></cite>].
- </p>
- </div>
- <div id="ecdsa-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"ECDSA"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>sign</td>
- <td><a href="#dfn-EcdsaParams">EcdsaParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>verify</td>
- <td><a href="#dfn-EcdsaParams">EcdsaParams</a></td>
- <td>boolean</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-EcKeyGenParams">EcKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
-
- </tbody>
- </table>
- </div>
- <div id="EcdsaParams-dictionary" class="section">
- <h4>EcdsaParams dictionary</h4>
- <x:codeblock language="idl">
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="rsa-oaep" class="section">
+ <h3>RSA-OAEP</h3>
+ <div id="rsa-oaep-description" class="section">
+ <h4>Description</h4>
+ <p>
+ The <code>"RSA-OAEP"</code> algorithm identifier is used to perform encryption
+ and decryption ordering to the RSAES-OAEP algorithm specified in
+ [<cite><a href="#RFC3447">RFC3447</a></cite>], using the mask
+ generation function MGF1.
+ </p>
+ </div>
+ <div id="rsa-oaep-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"RSA-OAEP"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>encrypt</td>
+ <td><a href="#dfn-RsaOaepParams">RsaOaepParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>decrypt</td>
+ <td><a href="#dfn-RsaOaepParams">RsaOaepParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <div id="rsa-oaep-params" class="section">
+ <h4>RsaOaepParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-RsaOaepParams">RsaOaepParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The optional label/application data to associate with the message</span>
+CryptoOperationData? <dfn id="dfn-RsaOaepParams-label">label</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="rsa-oaep-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Encrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of <var>key</var>
+ is not <code>"public"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the encryption operation defined in Section 7.1 of [<cite><a
+ href="#RFC3447">RFC3447</a></cite>] with the key represented by <var>key</var>
+ as the recipient's RSA public key, the <a
+ href="#concept-contents-of-arraybuffer">contents of <var>plaintext</var></a>
+ as the message to be encrypted, <var>M</var> and the <a
+ href="#concept-contents-of-arraybuffer">contents of</a> <a
+ href="#dfn-RsaOaepParams-label">label</a> member of
+ <var>normalizedAlgorithm</var> as the label, <var>L</var>, and with the hash
+ function specified by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option and MGF1 (defined in Section B.2.1 of
+ [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ciphertext</var> be a new <code>ArrayBuffer</code>
+ containing the value <var>C</var> that results from performing the
+ operation.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Decrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of <var>key</var>
+ is not <code>"private"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the decryption operation defined in Section 7.1 of [<cite><a
+ href="#RFC3447">RFC3447</a></cite>] with the key represented by <var>key</var>
+ as the recipient's RSA private key, the <a
+ href="#concept-contents-of-arraybuffer">contents of <var>ciphertext</var></a>
+ as the ciphertext to be decrypted, C, and the <a
+ href="#concept-contents-of-arraybuffer">contents of</a> the <a
+ href="#dfn-RsaOaepParams-label">label</a> member of
+ <var>normalizedAlgorithm</var> as the label, <var>L</var>, and with the hash
+ function specified by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option and MGF1 (defined in Section B.2.1 of
+ [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>plaintext</var> be a new <code>ArrayBuffer</code>
+ containing the value <var>M</var> that results from performing the
+ operation.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ <code>"encrypt"</code>, <code>"decrypt</code>,
+ <code>wrapKey</code> or <code>unwrapKey</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an RSA key pair, as defined in [<cite><a
+ href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> member of
+ <var>normalizedAlgorithm</var> and RSA public exponent equal to the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSA-OAEP"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
+ of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot of
+ <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the
+ <a href="#concept-usage-intersection">usage intersection</a> of
+ <var>usages</var> and <code>[ "encrypt", "wrapKey" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot of
+ <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be the
+ <a href="#concept-usage-intersection">usage intersection</a> of
+ <var>usages</var> and <code>[ "decrypt", "unwrapKey" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to be <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to be <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object, as
+ defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>Let <var>keyData</var> be the key data to be imported.</p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the
+ <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>algorithm</code> AlgorithmIdentifier field of
+ <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the <code>id-RSAES-OAEP</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>params</var> be the ASN.1 structure contained within
+ the <code>parameters</code> field of the <code>algorithm</code>
+ AlgorithmIdentifier field of <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not defined, or is not an instance of
+ the <code>RSAES-OAEP-params</code> ASN.1 type defined in
+ <a href="#RFC3447">RFC3447</a>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
+ within the <code>hashAlgorithm</code> field of <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ equivalent to the OID <code>id-mgf1</code> defined in <a
+ href="#RFC3447">RFC 3447</a>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ an instance of the <code>HashAlgorithm</code> ASN.1 type that is
+ identical in content to the <code>hashAlglorithm</code> field of
+ <var>params</var>, <a href="#concept-return-an-error">return an
+ error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be the result of performing the <a
+ href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
+ <var>structure</var> as the <code>RSAPublicKey</code> structure
+ specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA public key identified by
+ <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>privateKeyAlgorithm</code>
+ PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the <code>id-RSAES-OAEP</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>params</var> be the ASN.1 structure contained within
+ the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier
+ field of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not defined, or is not an instance of
+ the <code>RSAES-OAEP-params</code> ASN.1 type defined in <a
+ href="#RFC3447">RFC3447</a>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
+ within the <code>hashAlgorithm</code> field of
+ <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the
+ <code>id-sha256</code> OID defined in <a href="#RFC3447">RFC
+ 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the
+ <code>id-sha384</code> OID defined in <a href="#RFC3447">RFC
+ 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the
+ <code>id-sha512</code> OID defined in <a href="#RFC3447">RFC
+ 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ equivalent to the OID <code>id-mgf1</code> defined in <a
+ href="#RFC3447">RFC 3447</a>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ an instance of the <code>HashAlgorithm</code> ASN.1 type that is
+ identical in content to the <code>hashAlglorithm</code> field of
+ <var>params</var>, <a href="#concept-return-an-error">return an
+ error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>rsaPrivateKey</var> be the result of performing the <a
+ href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>privateKey</code> field of <var>privateKeyInfo</var>,
+ <var>structure</var> as the <code>RSAPrivateKey</code> structure
+ specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA private key identified by
+ <var>rsaPrivateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not a
+ case-sensitive string match to <code>"RSA"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not a case-sensitive string match to <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>alg</code> field of <var>jwk</var> is not present:</dt>
+ <dd>Let <var>hash</var> be undefined.</dd>
+ <dt>
+ If the <code>alg</code> field of <var>jwk</var> is equal to
+ <code>RSA-OAEP</code>:
+ </dt>
+ <dd>Let <var>hash</var> be the string <code>SHA-1</code>.</dd>
+ <dt>
+ If the <code>alg</code> field of <var>jwk</var> is equal to
+ <code>RSA-OAEP-256</code>:
+ </dt>
+ <dd>Let <var>hash</var> be the string <code>SHA-256</code>.</dd>
+ <dt>
+ If the <code>alg</code> field of <var>jwk</var> is equal to
+ <code>RSA-OAEP-384</code>:
+ </dt>
+ <dd>Let <var>hash</var> be the string <code>SHA-384</code>.</dd>
+ <dt>
+ If the <code>alg</code> field of <var>jwk</var> is equal to
+ <code>RSA-OAEP-512</code>:
+ </dt>
+ <dd>Let <var>hash</var> be the string <code>SHA-512</code>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a
+ href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a
+ href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.3.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a
+ href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA private key identified by interpreting <var>jwk</var>
+ according to Section 6.3.2 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a
+ href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA public key identified by interpreting <var>jwk</var>
+ according to Section 6.3.1 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSA-OAEP"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to the length, in bits, of the RSA public
+ modulus.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
+ representation of the RSA public exponent.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
+ <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> to <var>algorithm</var>
+ </p>
+ </li>
+ <li>
+ <p>Return <var>key</var>.</p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>key</var> be the key to be exported.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code></dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a
+ href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-RSAES-OAEP</code> defined in
+ <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>RSAES-OAEP-params</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>hashAlgorithm</var> field to an instance of
+ the <code>HashAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-1</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha1</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-256</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha256</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-384</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha384</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-512</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha512</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <var>maskGenAlgorithm</var> field to an instance
+ of the <code>MaskGenAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
+ 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>HashAlgorithm</code> ASN.1 type that is
+ identical to the <var>hashAlgorithm</var> field.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> field to the result of
+ DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
+ in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
+ represents the RSA public key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a
+ href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
+ with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>version</var> field to 0.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to an
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-RSAES-OAEP</code> defined in
+ <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>RSAES-OAEP-params</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>hashAlgorithm</var> field to an instance of
+ the <code>HashAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-1</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha1</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-256</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha256</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-384</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha384</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-512</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha512</code> defined in <a
+ href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <var>maskGenAlgorithm</var> field to an instance
+ of the <code>MaskGenAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
+ 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>HashAlgorithm</code> ASN.1 type that is
+ identical to the <var>hashAlgorithm</var> field.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to the result of DER-encoding
+ an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a
+ href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
+ RSA private key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ <div class="ednote">
+ <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
+ this field should be <em>BER</em> encoded in Section 5 (as a "for
+ example"). However, to avoid requiring WebCrypto implementations
+ support BER-encoding and BER-decoding, only <em>DER</em> encodings
+ are produced or accepted.
+ </div>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ul>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the string
+ <code>"RSA"</code>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>SHA-1</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>"RSA-OAEP"</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>SHA-256</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>"RSA-OAEP-256"</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>SHA-384</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>"RSA-OAEP-384"</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a
+ href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>SHA-512</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>"RSA-OAEP-512"</code>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
+ according to the corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.1.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is <code>"private"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Set the attributes named <code>d</code>, <code>p</code>,
+ <code>q</code>, <code>dp</code>, <code>dq</code>, and
+ <code>qi</code> of <var>jwk</var> according to the
+ corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.2.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying RSA private key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var> is represented by more than two primes, set
+ the attribute named <code>oth</code> of <var>jwk</var>
+ according to the corresponding definition in <a
+ href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a
+ href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ul>
+ </dd>
+ <dt>Otherwise</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="ecdsa" class="section">
+ <h3>ECDSA</h3>
+ <div id="ecdsa-description" class="section">
+ <h4>Description</h4>
+ <p>
+ The <code>"ECDSA"</code> algorithm identifier is used to perform signing
+ and verification using the ECDSA algorithm specified in
+ [<cite><a href="#X9.62">X9.62</a></cite>].
+ </p>
+ </div>
+ <div id="ecdsa-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"ECDSA"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sign</td>
+ <td><a href="#dfn-EcdsaParams">EcdsaParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>verify</td>
+ <td><a href="#dfn-EcdsaParams">EcdsaParams</a></td>
+ <td>boolean</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-EcKeyGenParams">EcKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+
+ </tbody>
+ </table>
+ </div>
+ <div id="EcdsaParams-dictionary" class="section">
+ <h4>EcdsaParams dictionary</h4>
+ <x:codeblock language="idl">
dictionary <dfn id="dfn-EcdsaParams">EcdsaParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The hash algorithm to use</span>
- AlgorithmIdentifier <dfn id="dfn-EcdsaParams-hash">hash</dfn>;
+<span class="comment">// The hash algorithm to use</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-EcdsaParams-hash">hash</dfn>;
};
- </x:codeblock>
- </div>
- <div id="EcKeyGenParams-dictionary" class="section">
- <h4>EcKeyGenParams dictionary</h4>
- <x:codeblock language="idl">
+ </x:codeblock>
+ </div>
+ <div id="EcKeyGenParams-dictionary" class="section">
+ <h4>EcKeyGenParams dictionary</h4>
+ <x:codeblock language="idl">
typedef DOMString <a href="#dfn-NamedCurve">NamedCurve</a>;
dictionary <dfn id="dfn-EcKeyGenParams">EcKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// A named curve</span>
- <a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyGenParams-namedCurve">namedCurve</dfn>;
-};
- </x:codeblock>
- <p>
- The <dfn id="dfn-NamedCurve">NamedCurve</dfn> type represents named elliptic curves,
- which are a convenient way to specify the domain parameters of well-known elliptic
- curves. The following values are recognized:
- </p>
- <dl>
- <dt id="dfn-NamedCurve-p256"><code>P-256</code></dt>
- <dd>NIST recommended curve P-256, also known as <code>secp256r1</code>.</dd>
- <dt id="dfn-NamedCurve-p2384"><code>P-384</code></dt>
- <dd>NIST recommended curve P-384, also known as <code>secp384r1</code>.</dd>
- <dt id="dfn-NamedCurve-p521"><code>P-521</code></dt>
- <dd>NIST recommended curve P-521, also known as <code>secp521r1</code>.</dd>
- </dl>
- </div>
- <div id="EcKeyAlgorithm-dictionary" class="section">
- <h4>EcKeyAlgorithm dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-EcKeyAlgorithm">EcKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
- <span class="comment">// The named curve that the key uses</span>
- <a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyAlgorithm-namedCurve">namedCurve</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="EcKeyImportParams-dictionary" class="section">
- <h4>EcKeyImportParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-EcKeyImportParams">EcKeyImportParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// A named curve</span>
- <a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyImportParams-namedCurve">namedCurve</dfn>;
+<span class="comment">// A named curve</span>
+<a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyGenParams-namedCurve">namedCurve</dfn>;
};
- </x:codeblock>
- </div>
-
- <div id="ecdsa-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Sign</dt>
- <dd>
- When signing, the following algorithm should be used:
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcdsaParams">EcdsaParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the properties of <a href="#dfn-EcdsaParams">EcdsaParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlgorithm</var> be the <a href="#dfn-EcdsaParams-hash">hash</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>hashAlgorithm</var> does not describe a
- <a href="#algorithms">registered algorithm</a> that supports the digest
- operation,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>M</var> be the result of performing the digest operation specified by
- <var>hashAlgorithm</var> using <var>message</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>d</var> be the ECDSA private key associated with <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the EC domain parameters associated with
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Perform the ECDSA signing process, as specified in <a href="#X9.62">X9.62</a>,
- Section 7.3, with <var>M</var> as the message, using <var>params</var> as the
- EC domain parameters, and with <var>d</var> as the private key.
- </p>
- </li>
- <li>
- <p>
- Let <var>r</var> and <var>s</var> be the pair of integers resulting from
- performing the ECDSA signing process.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code>.
- </p>
- </li>
- <li>
- <p>
- Convert <var>r</var> to a bitstring and append the sequence of bytes to
- <var>result</var>.
- </p>
- </li>
- <li>
- <p>
- Convert <var>s</var> to a bitstring and append the sequence of bytes to
- <var>result</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Verify</dt>
- <dd>
- When verifying, the following algorithm should be used:
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcdsaParams">EcdsaParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the properties of <a href="#dfn-EcdsaParams">EcdsaParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlgorithm</var> be the <a href="#dfn-EcdsaParams-hash">hash</a>
- member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>hashAlgorithm</var> does not describe a
- <a href="#algorithms">registered algorithm</a> that supports the digest
- operation,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>M</var> be the result of performing the digest operation specified by
- <var>hashAlgorithm</var> using <var>message</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>Q</var> be the ECDSA public key associated with <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the EC domain parameters associated with
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Perform the ECDSA verifying process, as specified in <a
- href="#X9.62">X9.62</a>, Section 7.4, with <var>M</var> as the received
- message, <var>signature</var> as the received signature and using
- <var>params</var> as the EC domain parameters, and
- <var>Q</var> as the public key.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a boolean indicating whether or not the purported
- signature is valid, with <code>true</code> indicating the signature is valid
- and <code>false</code> indicating it is invalid.
- </p>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcKeyGenParams">EcKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-EcKeyGenParams">EcKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains a value which is not
- one of <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an Elliptic Curve key pair, as defined in [<a href="#X9.62">X9.62</a>]
- with domain parameters for the curve identified by
- the <a href="#dfn-EcKeyGenParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If performing the key generation operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDSA"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-EcKeyGenParams">namedCurve</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the empty list.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
- intersection</a> of <var>usages</var> and <code>[ "sign", "verify" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to be <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to be <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object, as
- defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>Let <var>keyData</var> be the key data to be imported.</p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcKeyImportParams">EcKeyImportParams</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the
- <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
- algorithm over <var>keyData</var>
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is
- not equal to the <code>id-ecPublicKey</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the <code>algorithm</code>
- AlgorithmIdentifier field of <var>spki</var> is absent,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not an instance of the <code>namedCurve</code>
- ASN.1 type defined in <a href="#RFC5480">RFC 5480</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>params</var> is equivalent to the <code>secp256r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-256"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp384r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-384"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp521r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-521"</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is defined, and not equal to the <a
- href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the Elliptic Curve public key identified by
- performing the conversion steps defined in Section 2.2 of <a
- href="#RFC5480">RFC 5480</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a
- href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDSA"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurs while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithm field of
- <var>privateKeyInfo</var> is not equal to the
- <code>id-ecPublicKey</code> object identifier defined in <a
- href="#RFC5480">RFC 5480</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var> is not present,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If the <var>params</var> is not an instance of the
- <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
- 5480</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ecPrivateKey</var> be the result of performing the <a
- href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the <code>privateKey</code> field
- of <var>privateKeyInfo</var>, <var>structure</var> as the ASN.1
- <code>ECPrivateKey</code> structure specified in Section 3 of <a
- href="#RFC5915">RFC 5915</a>, and <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of <var>ecPrivateKey</var> is
- present, and is not an instance of the <code>namedCurve</code> ASN.1
- type defined in <a href="#RFC5480">RFC 5480</a>, or does not contain
- the same object identifier as the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>params</var> is equivalent to the <code>secp256r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-256"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp384r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-384"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp521r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-521"</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is defined, and not equal to the <a
- href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the Elliptic Curve private key identified by
- performing the conversion steps defined in Section 3 of <a
- href="#RFC5915">RFC 5915</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a
- href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDSA"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"EC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"sig"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of <a href="#jwk">JSON Web
- Key</a>, or it does not contain all of the specified <var>usages</var>
- values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose value is equal to the
- <code>"crv"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is not equal to the <a
- href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algNamedCurve</var> be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"alg"</code> field is present:</dt>
- <dd>
- Let <var>algNamedCurve</var> be undefined.
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string "ES256":
- </dt>
- <dd>
- Let <var>algNamedCurve</var> be the string <code>P-256</code>.
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string "ES384":
- </dt>
- <dd>
- Let <var>algNamedCurve</var> be the string <code>P-384</code>.
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string "ES521":
- </dt>
- <dd>
- Let <var>algNamedCurve</var> be the string <code>P-521</code>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>algNamedCurve</var> is defined, and is not equal to
- <var>namedCurve</var>, <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"d"</code> field is present:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a
- href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- Elliptic Curve private key identified by interpreting
- <var>jwk</var> according to Section 6.2.2 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>Key</var> to <code>"private"</code>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a
- href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- Elliptic Curve public key identified by interpreting
- <var>jwk</var> according to Section 6.2.1 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>Key</var> to <code>"public"</code>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new instance of an <a
- href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDSA"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>key</var>
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>key</var> be the <a href="#dfn-CryptoKey">CryptoKey</a> to be
- exported.
- </p>
- </li>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
+ </x:codeblock>
+ <p>
+ The <dfn id="dfn-NamedCurve">NamedCurve</dfn> type represents named elliptic curves,
+ which are a convenient way to specify the domain parameters of well-known elliptic
+ curves. The following values are recognized:
+ </p>
+ <dl>
+ <dt id="dfn-NamedCurve-p256"><code>P-256</code></dt>
+ <dd>NIST recommended curve P-256, also known as <code>secp256r1</code>.</dd>
+ <dt id="dfn-NamedCurve-p2384"><code>P-384</code></dt>
+ <dd>NIST recommended curve P-384, also known as <code>secp384r1</code>.</dd>
+ <dt id="dfn-NamedCurve-p521"><code>P-521</code></dt>
+ <dd>NIST recommended curve P-521, also known as <code>secp521r1</code>.</dd>
+ </dl>
+ </div>
+ <div id="EcKeyAlgorithm-dictionary" class="section">
+ <h4>EcKeyAlgorithm dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-EcKeyAlgorithm">EcKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
+<span class="comment">// The named curve that the key uses</span>
+<a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyAlgorithm-namedCurve">namedCurve</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="EcKeyImportParams-dictionary" class="section">
+ <h4>EcKeyImportParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-EcKeyImportParams">EcKeyImportParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// A named curve</span>
+<a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyImportParams-namedCurve">namedCurve</dfn>;
+};
+ </x:codeblock>
+ </div>
+
+ <div id="ecdsa-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Sign</dt>
+ <dd>
+ When signing, the following algorithm should be used:
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlgorithm</var> be the <a href="#dfn-EcdsaParams-hash">hash</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>hashAlgorithm</var> does not describe a
+ <a href="#algorithms">registered algorithm</a> that supports the digest
+ operation,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>M</var> be the result of performing the digest operation specified by
+ <var>hashAlgorithm</var> using <var>message</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>d</var> be the ECDSA private key associated with <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the EC domain parameters associated with
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the ECDSA signing process, as specified in <a href="#X9.62">X9.62</a>,
+ Section 7.3, with <var>M</var> as the message, using <var>params</var> as the
+ EC domain parameters, and with <var>d</var> as the private key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>r</var> and <var>s</var> be the pair of integers resulting from
+ performing the ECDSA signing process.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Convert <var>r</var> to a bitstring and append the sequence of bytes to
+ <var>result</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Convert <var>s</var> to a bitstring and append the sequence of bytes to
+ <var>result</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Verify</dt>
+ <dd>
+ When verifying, the following algorithm should be used:
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlgorithm</var> be the <a href="#dfn-EcdsaParams-hash">hash</a>
+ member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>hashAlgorithm</var> does not describe a
+ <a href="#algorithms">registered algorithm</a> that supports the digest
+ operation,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>M</var> be the result of performing the digest operation specified by
+ <var>hashAlgorithm</var> using <var>message</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>Q</var> be the ECDSA public key associated with <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the EC domain parameters associated with
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the ECDSA verifying process, as specified in <a
+ href="#X9.62">X9.62</a>, Section 7.4, with <var>M</var> as the received
+ message, <var>signature</var> as the received signature and using
+ <var>params</var> as the EC domain parameters, and
+ <var>Q</var> as the public key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a boolean indicating whether or not the purported
+ signature is valid, with <code>true</code> indicating the signature is valid
+ and <code>false</code> indicating it is invalid.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains a value which is not
+ one of <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an Elliptic Curve key pair, as defined in [<a href="#X9.62">X9.62</a>]
+ with domain parameters for the curve identified by
+ the <a href="#dfn-EcKeyGenParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the key generation operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDSA"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-EcKeyGenParams">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the empty list.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
+ intersection</a> of <var>usages</var> and <code>[ "sign", "verify" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to be <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to be <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object, as
+ defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>Let <var>keyData</var> be the key data to be imported.</p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the
+ <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
+ algorithm over <var>keyData</var>
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is
+ not equal to the <code>id-ecPublicKey</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the <code>algorithm</code>
+ AlgorithmIdentifier field of <var>spki</var> is absent,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not an instance of the <code>namedCurve</code>
+ ASN.1 type defined in <a href="#RFC5480">RFC 5480</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp256r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-256"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp384r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-384"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp521r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-521"</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is defined, and not equal to the <a
+ href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the Elliptic Curve public key identified by
+ performing the conversion steps defined in Section 2.2 of <a
+ href="#RFC5480">RFC 5480</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a
+ href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDSA"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurs while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithm field of
+ <var>privateKeyInfo</var> is not equal to the
+ <code>id-ecPublicKey</code> object identifier defined in <a
+ href="#RFC5480">RFC 5480</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var> is not present,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <var>params</var> is not an instance of the
+ <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
+ 5480</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ecPrivateKey</var> be the result of performing the <a
+ href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the <code>privateKey</code> field
+ of <var>privateKeyInfo</var>, <var>structure</var> as the ASN.1
+ <code>ECPrivateKey</code> structure specified in Section 3 of <a
+ href="#RFC5915">RFC 5915</a>, and <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of <var>ecPrivateKey</var> is
+ present, and is not an instance of the <code>namedCurve</code> ASN.1
+ type defined in <a href="#RFC5480">RFC 5480</a>, or does not contain
+ the same object identifier as the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp256r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-256"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp384r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-384"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp521r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-521"</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is defined, and not equal to the <a
+ href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the Elliptic Curve private key identified by
+ performing the conversion steps defined in Section 3 of <a
+ href="#RFC5915">RFC 5915</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a
+ href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDSA"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"EC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"sig"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of <a href="#jwk">JSON Web
+ Key</a>, or it does not contain all of the specified <var>usages</var>
+ values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose value is equal to the
+ <code>"crv"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is not equal to the <a
+ href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algNamedCurve</var> be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"alg"</code> field is present:</dt>
+ <dd>
+ Let <var>algNamedCurve</var> be undefined.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string "ES256":
+ </dt>
+ <dd>
+ Let <var>algNamedCurve</var> be the string <code>P-256</code>.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string "ES384":
+ </dt>
+ <dd>
+ Let <var>algNamedCurve</var> be the string <code>P-384</code>.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string "ES521":
+ </dt>
+ <dd>
+ Let <var>algNamedCurve</var> be the string <code>P-521</code>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>algNamedCurve</var> is defined, and is not equal to
+ <var>namedCurve</var>, <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"d"</code> field is present:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a
+ href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ Elliptic Curve private key identified by interpreting
+ <var>jwk</var> according to Section 6.2.2 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>Key</var> to <code>"private"</code>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a
+ href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ Elliptic Curve public key identified by interpreting
+ <var>jwk</var> according to Section 6.2.1 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>Key</var> to <code>"public"</code>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new instance of an <a
+ href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDSA"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>key</var> be the <a href="#dfn-CryptoKey">CryptoKey</a> to be
+ exported.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a
+ href="#concept-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> object identifier to the OID
+ <code>1.2.840.10045.2.1</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>namedCurve</code> ASN.1 type as follows:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp256r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp384r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-521"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp521r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> field to the octet string that
+ represents the Elliptic Curve public key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> according to the encoding rules specified in
+ Section 2.2 of <a href="#RFC5480">RFC 5480</a> and using the
+ uncompressed form.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a
+ href="#concept-encode-a-privateKeyInfo">encoding a
+ privateKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>version</var> field to <code>0</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to an
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> object identifier to the OID
+ <code>1.2.840.10045.2.1</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>namedCurve</code> ASN.1 type as follows:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp256r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp384r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-521"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp521r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to the result of DER-encoding
+ an instance of the <code>ECPrivateKey</code> structure defined in
+ Section 3 of <a href="#RFC5915">RFC 5915</a> for the Elliptic
+ Curve private key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> and that conforms to the following:
+ </p>
+ <ul>
+ <li>
+ <p>
+ The <var>parameters</var> field is present, and is equivalent
+ to the <var>parameters</var> field of the
+ <var>privateKeyAlgorithm</var> field of this
+ <code>PrivateKeyInfo</code> ASN.1 structure.
+ </p>
+ </li>
+ <li>
+ <p>
+ The <var>publicKey</var> field is present and represents the
+ Elliptic Curve public key associated with the Elliptic Curve
+ private key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to
+ <code>"EC"</code>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-256</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-256"</code>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-384</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-384"</code>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-521</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-521"</code>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>x</code> attribute of <var>jwk</var> according to the
+ definition in Section 6.2.1.2 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>y</code> attribute of <var>jwk</var> according to the
+ definition in Section 6.2.1.3 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a
- href="#concept-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> object identifier to the OID
- <code>1.2.840.10045.2.1</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>namedCurve</code> ASN.1 type as follows:
- </p>
- <dl class="switch">
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-256"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp256r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-384"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp384r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-521"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp521r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- </dl>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> field to the octet string that
- represents the Elliptic Curve public key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> according to the encoding rules specified in
- Section 2.2 of <a href="#RFC5480">RFC 5480</a> and using the
- uncompressed form.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a
- href="#concept-encode-a-privateKeyInfo">encoding a
- privateKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>version</var> field to <code>0</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to an
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> object identifier to the OID
- <code>1.2.840.10045.2.1</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>namedCurve</code> ASN.1 type as follows:
- </p>
- <dl class="switch">
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-256"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp256r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-384"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp384r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-521"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp521r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- </dl>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to the result of DER-encoding
- an instance of the <code>ECPrivateKey</code> structure defined in
- Section 3 of <a href="#RFC5915">RFC 5915</a> for the Elliptic
- Curve private key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> and that conforms to the following:
- </p>
- <ul>
- <li>
- <p>
- The <var>parameters</var> field is present, and is equivalent
- to the <var>parameters</var> field of the
- <var>privateKeyAlgorithm</var> field of this
- <code>PrivateKeyInfo</code> ASN.1 structure.
- </p>
- </li>
- <li>
- <p>
- The <var>publicKey</var> field is present and represents the
- Elliptic Curve public key associated with the Elliptic Curve
- private key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to
- <code>"EC"</code>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-256</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-256"</code>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-384</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-384"</code>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-521</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-521"</code>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>x</code> attribute of <var>jwk</var> according to the
- definition in Section 6.2.1.2 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>y</code> attribute of <var>jwk</var> according to the
- definition in Section 6.2.1.3 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>private</code>
- </dt>
- <dd>
- <p>
- Set the <code>d</code> attribute of <var>jwk</var> according to
- the definition in Section 6.2.2.1 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a
- href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="ecdh" class="section">
- <h3>ECDH</h3>
- <div id="ecdh-description" class="section">
- <h4>Description</h4>
- <p>
- This describes using Elliptic Curve Diffie-Hellman (ECDH) for key generation and key
- agreement, as specified by <a href="#X9.63">X9.63</a>.
- </p>
- </div>
- <div id="ecdh-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"ECDH"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-EcKeyGenParams">EcKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>deriveBits</td>
- <td><a href="#dfn-EcdhKeyDeriveParams">EcdhKeyDeriveParams</a></td>
- <td>Octet string</td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-EcKeyImportParams">EcKeyImportParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="dh-EcdhKeyDeriveParams" class="section">
- <h4>EcdhKeyDeriveParams dictionary</h4>
- <x:codeblock language="idl">
+ of <var>key</var> is <code>private</code>
+ </dt>
+ <dd>
+ <p>
+ Set the <code>d</code> attribute of <var>jwk</var> according to
+ the definition in Section 6.2.2.1 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a
+ href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="ecdh" class="section">
+ <h3>ECDH</h3>
+ <div id="ecdh-description" class="section">
+ <h4>Description</h4>
+ <p>
+ This describes using Elliptic Curve Diffie-Hellman (ECDH) for key generation and key
+ agreement, as specified by <a href="#X9.63">X9.63</a>.
+ </p>
+ </div>
+ <div id="ecdh-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"ECDH"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-EcKeyGenParams">EcKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>deriveBits</td>
+ <td><a href="#dfn-EcdhKeyDeriveParams">EcdhKeyDeriveParams</a></td>
+ <td>Octet string</td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-EcKeyImportParams">EcKeyImportParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="dh-EcdhKeyDeriveParams" class="section">
+ <h4>EcdhKeyDeriveParams dictionary</h4>
+ <x:codeblock language="idl">
typedef Uint8Array <dfn id="dfn-ECPoint">ECPoint</dfn>;
dictionary <dfn id="dfn-EcdhKeyDeriveParams">EcdhKeyDeriveParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The peer's EC public key.</span>
- <a href="#dfn-CryptoKey">CryptoKey</a> <dfn id="dfn-EcdhKeyDeriveParams-public">public</dfn>;
+<span class="comment">// The peer's EC public key.</span>
+<a href="#dfn-CryptoKey">CryptoKey</a> <dfn id="dfn-EcdhKeyDeriveParams-public">public</dfn>;
};
- </x:codeblock>
- </div>
- <div id="ecdh-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcKeyGenParams">EcKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-EcKeyGenParams">EcKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains a value which is not
- one of <code>"deriveKey"</code> or <code>"deriveBits"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an Elliptic Curve key pair, as defined in [<a
- href="#X9.63">X9.63</a>] with domain parameters for the curve identified by
- the <a href="#dfn-EcKeyGenParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-Algorithm-name">name</a> member of
- <var>algorithm</var> to <code>"ECDH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-EcKeyGenParams">namedCurve</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the empty list.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be the
- <a href="#concept-usage-intersection">usage intersection</a> of
- <var>usages</var> and <code>[ "deriveKey", "deriveBits" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to be <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to be <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object, as
- defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- <dt>Derive Bits</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcdhKeyDeriveParams">EcdhKeyDeriveParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a
- href="#dfn-EcdhKeyDeriveParams">EcdhKeyDeriveParams</a> are not present in
- <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be the
- <a href="#dfn-EcdhKeyDeriveParams-public">public</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> is not <code>"ECDH"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> is not equal to the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a> property of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
- named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the ECDH primitive specified in <a href="#X9.63">X9.63</a> Section
- 5.4.1 with <var>key</var> as the EC private key <var>d</var> and the EC public
- key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
- internal slot of <var>publicKey</var> as the EC public key <var>Q</var>.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>secret</var> be the result of applying the field element to
- octet string conversion defined in Section ? of <a href="#X9.63">X9.63</a>
- to the output of the ECDH primitive.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>length</var> is null:</dt>
- <dd>Return <var>secret</var></dd>
- <dt>Otherwise:</dt>
- <dd>
- <dl class="switch">
- <dt>
- If the length of <var>secret</var> in bits is less than
- <var>length</var>:
- </dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>Return the first <var>length</var> bits of <var>secret</var>.</dd>
- </dl>
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
-
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>Let <var>keyData</var> be the key data to be imported.</p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcKeyImportParams">EcKeyImportParams</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the
- <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
- algorithm over <var>keyData</var>
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is
- not equal to the <code>id-ecPublicKey</code> or <code>id-ecDH</code>
- object identifiers defined in <a href="#RFC5480">RFC 5480</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the <code>algorithm</code>
- AlgorithmIdentifier field of <var>spki</var> is absent,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not an instance of the
- <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
- 5480</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>params</var> is equivalent to the <code>secp256r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-256"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp384r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-384"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp521r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-521"</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is defined, and not equal to the <a
- href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the Elliptic Curve public key identified by
- performing the conversion steps defined in Section 2.2 of <a
- href="#RFC5480">RFC 5480</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a
- href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurs while parsing,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithm field of
- <var>privateKeyInfo</var> is not equal to the
- <code>id-ecPublicKey</code> or <code>id-ecDH</code> object identifiers
- defined in <a href="#RFC5480">RFC 5480</a>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var> is not present,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If the <var>params</var> is not an instance of the
- <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
- 5480</a>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ecPrivateKey</var> be the result of performing the
- <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the <code>privateKey</code> field
- of <var>privateKeyInfo</var>, <var>structure</var> as the ASN.1
- <code>ECPrivateKey</code> structure specified in Section 3 of
- <a href="#RFC5915">RFC 5915</a>, and <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of <var>ecPrivateKey</var> is
- present, and is not an instance of the <code>namedCurve</code> ASN.1
- type defined in <a href="#RFC5480">RFC 5480</a>, or does not contain
- the same object identifier as the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>params</var> is equivalent to the <code>secp256r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-256"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp384r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-384"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp521r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-521"</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is defined, and not equal to the <a
- href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the Elliptic Curve private key identified by
- performing the conversion steps defined in Section 3 of <a
- href="#RFC5915">RFC 5915</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"private"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a
- href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is
- to <code>"EC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of <a href="#jwk">JSON Web
- Key</a>, or it does not contain all of the specified <var>usages</var>
- values, then <a href="#concept-return-an-error">return an error</a>
- named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose value is equal to the
- <code>"crv"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is not equal to the <a
- href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"d"</code> field is present:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a
- href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- Elliptic Curve private key identified by interpreting
- <var>jwk</var> according to Section 6.2.2 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>Key</var> to <code>"private"</code>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a
- href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- Elliptic Curve public key identified by interpreting
- <var>jwk</var> according to Section 6.2.1 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>Key</var> to <code>"public"</code>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new instance of an <a
- href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If any of the members of <a
- href="#dfn-EcKeyImportParams">EcKeyImportParams</a> are not present in
- <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a>
- member of <var>normalizedAlgorithm</var> is not a
- <a href="#dfn-NamedCurve">named curve</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> is not the empty list,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>extractable</var> is false,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>Q</var> be the elliptic curve point on the curve identified
- by the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a>
- member of <var>normalizedAlgorithm</var> identified by interpreting
- <var>keyData</var> according to <a href="#X9.62">X9.62</a> Annex A.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a
- href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to equal the <a
- href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal
- slot of <var>key</var> to <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
+ </x:codeblock>
+ </div>
+ <div id="ecdh-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If any of the members of <a href="#dfn-EcKeyGenParams">EcKeyGenParams</a> are
+ not present in <var>normalizedAlgorithm</var>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains a value which is not
+ one of <code>"deriveKey"</code> or <code>"deriveBits"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an Elliptic Curve key pair, as defined in [<a
+ href="#X9.63">X9.63</a>] with domain parameters for the curve identified by
+ the <a href="#dfn-EcKeyGenParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>algorithm</var> to <code>"ECDH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-EcKeyGenParams">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the empty list.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be the
+ <a href="#concept-usage-intersection">usage intersection</a> of
+ <var>usages</var> and <code>[ "deriveKey", "deriveBits" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to be <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to be <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object, as
+ defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Derive Bits</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be the
+ <a href="#dfn-EcdhKeyDeriveParams-public">public</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> is not <code>"ECDH"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> is not equal to the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a> property of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
+ named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the ECDH primitive specified in <a href="#X9.63">X9.63</a> Section
+ 5.4.1 with <var>key</var> as the EC private key <var>d</var> and the EC public
+ key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
+ internal slot of <var>publicKey</var> as the EC public key <var>Q</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>secret</var> be the result of applying the field element to
+ octet string conversion defined in Section ? of <a href="#X9.63">X9.63</a>
+ to the output of the ECDH primitive.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>length</var> is null:</dt>
+ <dd>Return <var>secret</var></dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <dl class="switch">
+ <dt>
+ If the length of <var>secret</var> in bits is less than
+ <var>length</var>:
+ </dt>
+ <dd>
<a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>key</var>
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>key</var> be the <a href="#dfn-CryptoKey">CryptoKey</a> to be
- exported.
- </p>
- </li>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of <a
- href="#concept-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> object identifier to the OID
- <code>1.3.132.112</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>namedCurve</code> ASN.1 type as follows:
- </p>
- <dl class="switch">
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-256"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp256r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-384"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp384r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-521"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp521r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- </dl>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> field to the octet string that
- represents the Elliptic Curve public key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> according to the encoding rules specified in
- Section 2.2 of <a href="#RFC5480">RFC 5480</a> and using the
- uncompressed form.
- </p>
- </li>
- </ul>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of <a
- href="#concept-encode-a-privateKeyInfo">encoding a
- privateKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>version</var> field to <code>0</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to an
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> object identifier to the OID
- <code>1.3.132.112</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>namedCurve</code> ASN.1 type as follows:
- </p>
- <dl class="switch">
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-256"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp256r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-384"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp384r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a
- href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-521"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp521r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- </dl>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to the result of DER-encoding
- an instance of the <code>ECPrivateKey</code> structure defined in
- Section 3 of <a href="#RFC5915">RFC 5915</a> for the Elliptic
- Curve private key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> and that conforms to the following:
- </p>
- <ul>
- <li>
- <p>
- The <var>parameters</var> field is present, and is equivalent
- to the <var>parameters</var> field of the
- <var>privateKeyAlgorithm</var> field of this
- <code>PrivateKeyInfo</code> ASN.1 structure.
- </p>
- </li>
- <li>
- <p>
- The <var>publicKey</var> field is present and represents the
- Elliptic Curve public key associated with the Elliptic Curve
- private key represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to
- <code>"EC"</code>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-256</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-256"</code>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-384</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-384"</code>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-521</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-521"</code>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>x</code> attribute of <var>jwk</var> according to the
- definition in Section 6.2.1.2 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>y</code> attribute of <var>jwk</var> according to the
- definition in Section 6.2.1.3 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>private</code>
- </dt>
- <dd>
- <p>
- Set the <code>d</code> attribute of <var>jwk</var> according to the
- definition in Section 6.2.2.1 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- <dt>
- If <var>format</var> is <code>"raw"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be an octet string representing the Elliptic Curve
- point <var>Q</var> represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> according to <a href="#X9.62">X9.62</a> Annex A.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="aes-ctr" class="section">
- <h3>AES-CTR</h3>
- <div id="aes-ctr-description" class="section">
- <h4>Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"AES-CTR"</code> algorithm identifier is used to perform
- encryption and decryption using AES in Counter mode,
- as described in NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>].
- </p>
- </div>
- <div id="aes-ctr-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-CTR"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>encrypt</td>
- <td><a href="#dfn-AesCtrParams">AesCtrParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>decrypt</td>
- <td><a href="#dfn-AesCtrParams">AesCtrParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
-
- <div id="aes-ctr-params" class="section">
- <h4>AesCtrParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-AesCtrParams">AesCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The initial value of the counter block. counter <span class="RFC2119">MUST</span> be 16 bytes
- // (the AES block size). The counter bits are the rightmost length
- // bits of the counter block. The rest of the counter block is for
- // the nonce. The counter bits are incremented using the standard
- // incrementing function specified in NIST SP 800-38A Appendix B.1:
- // the counter bits are interpreted as a big-endian integer and
- // incremented by one.</span>
- CryptoOperationData <dfn id="dfn-AesCtrParams-counter">counter</dfn>;
- <span class="comment">// The length, in bits, of the rightmost part of the counter block
- // that is incremented.</span>
- [EnforceRange] octet <dfn id="dfn-AesCtrParams-length">length</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="AesKeyAlgorithm-dictionary" class="section">
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-AesKeyAlgorithm">AesKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
- <span class="comment">// The length, in bits, of the key.</span>
- unsigned short <dfn id="dfn-AesKeyAlgorithm-length">length</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="aes-keygen-params" class="section">
- <h4>AesKeyGenParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-AesKeyGenParams">AesKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The length, in bits, of the key.</span>
- [EnforceRange] unsigned short <dfn id="dfn-AesKeyGenParams-length">length</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="aes-derivedkey-params" class="section">
- <h4>AesDerivedKeyParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-AesDerivedKeyParams">AesDerivedKeyParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The length, in bits, of the key.</span>
- [EnforceRange] unsigned short <dfn id="dfn-AesDerivedKeyParams-length">length</dfn>;
-};
- </x:codeblock>
- </div>
-
- <div id="aes-ctr-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Encrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCtrParams">AesCtrParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-ctr-params">AesCtrParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCtrParams-counter">counter</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCtrParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is zero or is greater
- than 128,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ciphertext</var> be the result of performing the CTR Encryption
- operation described in Section 6.5 of NIST SP 800-38A [<a
- href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
- href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-AesCtrParams-counter">counter</a> member of
- <var>normalizedAlgorithm</var> as the initial value of the counter block, the
- <a href="#dfn-AesCtrParams-length">length</a> member of
- <var>normalizedAlgorithm</var> as the input parameter <var>m</var> to the
- standard counter block incrementing function defined in Appendix B.1 of NIST SP
- 800-38A [<a href="#SP800-38A">SP800-38A</a>] and <a
- href="#concept-contents-of-arraybuffer">the contents of
- <var>plaintext</var></a> as the input plaintext.
- </p>
- </li>
- <li>
- <p>
- Return <var>ciphertext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Decrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCtrParams">AesCtrParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-ctr-params">AesCtrParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCtrParams-counter">counter</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCtrParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is zero or is greater
- than 128,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>plaintext</var> be the result of performing the CTR Decryption
- operation described in Section 6.5 of NIST SP 800-38A [<a
- href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
- href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-AesCtrParams-counter">counter</a> member of
- <var>normalizedAlgorithm</var> as the initial value of the counter block, the
- <a href="#dfn-AesCtrParams-length">length</a> member of
- <var>normalizedAlgorithm</var> as the input parameter <var>m</var> to the
- standard counter block incrementing function defined in Appendix B.1 of NIST SP
- 800-38A [<a href="#SP800-38A">SP800-38A</a>] and <a
- href="#concept-contents-of-arraybuffer">the contents of
- <var>ciphertext</var></a> as the input ciphertext.
- </p>
- </li>
- <li>
- <p>
- Return <var>plaintext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an AES key of length
- equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CTR"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128CTR"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192CTR"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256CTR"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>Return the first <var>length</var> bits of <var>secret</var>.</dd>
+ </dl>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>Let <var>keyData</var> be the key data to be imported.</p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the
+ <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
+ algorithm over <var>keyData</var>
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is
+ not equal to the <code>id-ecPublicKey</code> or <code>id-ecDH</code>
+ object identifiers defined in <a href="#RFC5480">RFC 5480</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the <code>algorithm</code>
+ AlgorithmIdentifier field of <var>spki</var> is absent,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not an instance of the
+ <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
+ 5480</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp256r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-256"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp384r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-384"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp521r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-521"</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
<a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is defined, and not equal to the <a
+ href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the Elliptic Curve public key identified by
+ performing the conversion steps defined in Section 2.2 of <a
+ href="#RFC5480">RFC 5480</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a
+ href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurs while parsing,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithm field of
+ <var>privateKeyInfo</var> is not equal to the
+ <code>id-ecPublicKey</code> or <code>id-ecDH</code> object identifiers
+ defined in <a href="#RFC5480">RFC 5480</a>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var> is not present,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <var>params</var> is not an instance of the
+ <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
+ 5480</a>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ecPrivateKey</var> be the result of performing the
+ <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the <code>privateKey</code> field
+ of <var>privateKeyInfo</var>, <var>structure</var> as the ASN.1
+ <code>ECPrivateKey</code> structure specified in Section 3 of
+ <a href="#RFC5915">RFC 5915</a>, and <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of <var>ecPrivateKey</var> is
+ present, and is not an instance of the <code>namedCurve</code> ASN.1
+ type defined in <a href="#RFC5480">RFC 5480</a>, or does not contain
+ the same object identifier as the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp256r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-256"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp384r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-384"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp521r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-521"</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is defined, and not equal to the <a
+ href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the Elliptic Curve private key identified by
+ performing the conversion steps defined in Section 3 of <a
+ href="#RFC5915">RFC 5915</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"private"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a
+ href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is
+ to <code>"EC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of <a href="#jwk">JSON Web
+ Key</a>, or it does not contain all of the specified <var>usages</var>
+ values, then <a href="#concept-return-an-error">return an error</a>
+ named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose value is equal to the
+ <code>"crv"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is not equal to the <a
+ href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"d"</code> field is present:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a
+ href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ Elliptic Curve private key identified by interpreting
+ <var>jwk</var> according to Section 6.2.2 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>Key</var> to <code>"private"</code>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a
+ href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ Elliptic Curve public key identified by interpreting
+ <var>jwk</var> according to Section 6.2.1 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>Key</var> to <code>"public"</code>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new instance of an <a
+ href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If any of the members of <a
+ href="#dfn-EcKeyImportParams">EcKeyImportParams</a> are not present in
+ <var>normalizedAlgorithm</var>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a>
+ member of <var>normalizedAlgorithm</var> is not a
+ <a href="#dfn-NamedCurve">named curve</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> is not the empty list,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>extractable</var> is false,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>Q</var> be the elliptic curve point on the curve identified
+ by the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a>
+ member of <var>normalizedAlgorithm</var> identified by interpreting
+ <var>keyData</var> according to <a href="#X9.62">X9.62</a> Annex A.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a
+ href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to equal the <a
+ href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal
+ slot of <var>key</var> to <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
<a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a
- href="#dfn-CryptoKey">CryptoKey</a></code> object representing an AES key with
- value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CTR"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128CTR"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192CTR"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256CTR"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="aes-cbc" class="section">
- <h3>AES-CBC</h3>
- <div id="aes-cbc-description" class="section">
- <h4>Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"AES-CBC"</code> algorithm identifier is used to perform
- encryption and decryption using AES in Cipher Block Chaining mode,
- as described in NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>].
- </p>
- <p>
- When operating in CBC mode, messages that are not exact multiples
- of the AES block size (16 bytes) can be padded under a variety of
- padding schemes. In the Web Crypto API, the only padding mode that
- is supported is that of PKCS#7, as described by
- Section 10.3, step 2, of RFC 2315 [<a href="#RFC2315">RFC2315</a>].
- </p>
- </div>
- <div id="aes-cbc-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-CBC"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>encrypt</td>
- <td><a href="#dfn-AesCbcParams">AesCbcParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>decrypt</td>
- <td><a href="#dfn-AesCbcParams">AesCbcParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="aes-cbc-params" class="section">
- <h4>AesCbcParams dictionary</h4>
- <x:codeblock language="idl">
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>key</var> be the <a href="#dfn-CryptoKey">CryptoKey</a> to be
+ exported.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of <a
+ href="#concept-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> object identifier to the OID
+ <code>1.3.132.112</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>namedCurve</code> ASN.1 type as follows:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp256r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp384r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-521"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp521r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> field to the octet string that
+ represents the Elliptic Curve public key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> according to the encoding rules specified in
+ Section 2.2 of <a href="#RFC5480">RFC 5480</a> and using the
+ uncompressed form.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of <a
+ href="#concept-encode-a-privateKeyInfo">encoding a
+ privateKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>version</var> field to <code>0</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to an
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> object identifier to the OID
+ <code>1.3.132.112</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>namedCurve</code> ASN.1 type as follows:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp256r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp384r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a
+ href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-521"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp521r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to the result of DER-encoding
+ an instance of the <code>ECPrivateKey</code> structure defined in
+ Section 3 of <a href="#RFC5915">RFC 5915</a> for the Elliptic
+ Curve private key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> and that conforms to the following:
+ </p>
+ <ul>
+ <li>
+ <p>
+ The <var>parameters</var> field is present, and is equivalent
+ to the <var>parameters</var> field of the
+ <var>privateKeyAlgorithm</var> field of this
+ <code>PrivateKeyInfo</code> ASN.1 structure.
+ </p>
+ </li>
+ <li>
+ <p>
+ The <var>publicKey</var> field is present and represents the
+ Elliptic Curve public key associated with the Elliptic Curve
+ private key represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to
+ <code>"EC"</code>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-256</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-256"</code>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-384</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-384"</code>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-521</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-521"</code>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>x</code> attribute of <var>jwk</var> according to the
+ definition in Section 6.2.1.2 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>y</code> attribute of <var>jwk</var> according to the
+ definition in Section 6.2.1.3 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is <code>private</code>
+ </dt>
+ <dd>
+ <p>
+ Set the <code>d</code> attribute of <var>jwk</var> according to the
+ definition in Section 6.2.2.1 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ If <var>format</var> is <code>"raw"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be an octet string representing the Elliptic Curve
+ point <var>Q</var> represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> according to <a href="#X9.62">X9.62</a> Annex A.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="aes-ctr" class="section">
+ <h3>AES-CTR</h3>
+ <div id="aes-ctr-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-CTR"</code> algorithm identifier is used to perform
+ encryption and decryption using AES in Counter mode,
+ as described in NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>].
+ </p>
+ </div>
+ <div id="aes-ctr-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-CTR"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>encrypt</td>
+ <td><a href="#dfn-AesCtrParams">AesCtrParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>decrypt</td>
+ <td><a href="#dfn-AesCtrParams">AesCtrParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <div id="aes-ctr-params" class="section">
+ <h4>AesCtrParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-AesCtrParams">AesCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The initial value of the counter block. counter <span class="RFC2119">MUST</span> be 16 bytes
+// (the AES block size). The counter bits are the rightmost length
+// bits of the counter block. The rest of the counter block is for
+// the nonce. The counter bits are incremented using the standard
+// incrementing function specified in NIST SP 800-38A Appendix B.1:
+// the counter bits are interpreted as a big-endian integer and
+// incremented by one.</span>
+CryptoOperationData <dfn id="dfn-AesCtrParams-counter">counter</dfn>;
+<span class="comment">// The length, in bits, of the rightmost part of the counter block
+// that is incremented.</span>
+[EnforceRange] octet <dfn id="dfn-AesCtrParams-length">length</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="AesKeyAlgorithm-dictionary" class="section">
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-AesKeyAlgorithm">AesKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
+<span class="comment">// The length, in bits, of the key.</span>
+unsigned short <dfn id="dfn-AesKeyAlgorithm-length">length</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="aes-keygen-params" class="section">
+ <h4>AesKeyGenParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-AesKeyGenParams">AesKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The length, in bits, of the key.</span>
+[EnforceRange] unsigned short <dfn id="dfn-AesKeyGenParams-length">length</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="aes-derivedkey-params" class="section">
+ <h4>AesDerivedKeyParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-AesDerivedKeyParams">AesDerivedKeyParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The length, in bits, of the key.</span>
+[EnforceRange] unsigned short <dfn id="dfn-AesDerivedKeyParams-length">length</dfn>;
+};
+ </x:codeblock>
+ </div>
+
+ <div id="aes-ctr-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Encrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCtrParams-counter">counter</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCtrParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is zero or is greater
+ than 128,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ciphertext</var> be the result of performing the CTR Encryption
+ operation described in Section 6.5 of NIST SP 800-38A [<a
+ href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
+ href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-AesCtrParams-counter">counter</a> member of
+ <var>normalizedAlgorithm</var> as the initial value of the counter block, the
+ <a href="#dfn-AesCtrParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> as the input parameter <var>m</var> to the
+ standard counter block incrementing function defined in Appendix B.1 of NIST SP
+ 800-38A [<a href="#SP800-38A">SP800-38A</a>] and <a
+ href="#concept-contents-of-arraybuffer">the contents of
+ <var>plaintext</var></a> as the input plaintext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>ciphertext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Decrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCtrParams-counter">counter</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCtrParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is zero or is greater
+ than 128,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>plaintext</var> be the result of performing the CTR Decryption
+ operation described in Section 6.5 of NIST SP 800-38A [<a
+ href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
+ href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-AesCtrParams-counter">counter</a> member of
+ <var>normalizedAlgorithm</var> as the initial value of the counter block, the
+ <a href="#dfn-AesCtrParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> as the input parameter <var>m</var> to the
+ standard counter block incrementing function defined in Appendix B.1 of NIST SP
+ 800-38A [<a href="#SP800-38A">SP800-38A</a>] and <a
+ href="#concept-contents-of-arraybuffer">the contents of
+ <var>ciphertext</var></a> as the input ciphertext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>plaintext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not equal to one of
+ 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an AES key of length
+ equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CTR"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"oct"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128CTR"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192CTR"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256CTR"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a
+ href="#dfn-CryptoKey">CryptoKey</a></code> object representing an AES key with
+ value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CTR"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128CTR"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192CTR"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256CTR"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="aes-cbc" class="section">
+ <h3>AES-CBC</h3>
+ <div id="aes-cbc-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-CBC"</code> algorithm identifier is used to perform
+ encryption and decryption using AES in Cipher Block Chaining mode,
+ as described in NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>].
+ </p>
+ <p>
+ When operating in CBC mode, messages that are not exact multiples
+ of the AES block size (16 bytes) can be padded under a variety of
+ padding schemes. In the Web Crypto API, the only padding mode that
+ is supported is that of PKCS#7, as described by
+ Section 10.3, step 2, of RFC 2315 [<a href="#RFC2315">RFC2315</a>].
+ </p>
+ </div>
+ <div id="aes-cbc-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-CBC"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>encrypt</td>
+ <td><a href="#dfn-AesCbcParams">AesCbcParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>decrypt</td>
+ <td><a href="#dfn-AesCbcParams">AesCbcParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="aes-cbc-params" class="section">
+ <h4>AesCbcParams dictionary</h4>
+ <x:codeblock language="idl">
dictionary <dfn id="dfn-AesCbcParams">AesCbcParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The initialization vector. <span class="RFC2119">MUST</span> be 16 bytes.</span>
- CryptoOperationData <dfn id="dfn-AesCbcParams-iv">iv</dfn>;
+<span class="comment">// The initialization vector. <span class="RFC2119">MUST</span> be 16 bytes.</span>
+CryptoOperationData <dfn id="dfn-AesCbcParams-iv">iv</dfn>;
};
- </x:codeblock>
- </div>
- <div id="aes-cbc-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Encrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCbcParams">AesCbcParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-cbc-params">AesCbcParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCbcParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
+ </x:codeblock>
+ </div>
+ <div id="aes-cbc-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Encrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCbcParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>paddedPlaintext</var> be the result of adding padding octets to
+ <var>ciphertext</var> according to the procedure defined in Section 10.3
+ of RFC 2315 [<a href="#RFC2315">RFC2315</a>], step 2, with a value of
+ <var>k</var> of 16.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ciphertext</var> be the result of performing the CBC Encryption
+ operation described in Section 6.2 of NIST SP 800-38A [<a
+ href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
+ href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-AesCbcParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter and <a
+ href="#concept-contents-of-arraybuffer">the contents of
+ <var>paddedPlaintext</var></a> as the input plaintext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>ciphertext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Decrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCbcParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>paddedPlaintext</var> be the result of performing the CBC Decryption
+ operation described in Section 6.2 of NIST SP 800-38A [<a
+ href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
+ href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-AesCbcParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter and <a
+ href="#concept-contents-of-arraybuffer">the contents of
+ <var>ciphertext</var></a> as the input ciphertext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>p</var> be the value of the last octet of <var>paddedPlaintext</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>p</var> is zero or greater than 16, or if any of the last <var>p</var>
+ octets of <var>paddedPlaintext</var> have a value which is not <var>p</var>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>plaintext</var> be the result of removing <var>p</var> octets from
+ the end of <var>paddedPlaintext</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>plaintext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not equal to one of
+ 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an AES key of length
+ equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CBC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ to <code>"oct"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128CBC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192CBC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256CBC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
+ object representing an AES key with value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CBC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128CBC"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192CBC"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256CBC"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="aes-cmac" class="section">
+ <h3>AES-CMAC</h3>
+ <div id="aes-cmac-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-CMAC"</code> algorithm identifier is used to perform
+ message authentication using AES with a cipher-based MAC, as
+ described in NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>].
+ </p>
+ </div>
+ <div id="aes-cmac-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-CMAC"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sign</td>
+ <td><a href="#dfn-AesCmacParams">AesCmacParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>verify</td>
+ <td><a href="#dfn-AesCmacParams">AesCmacParams</a></td>
+ <td>boolean</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="aes-cmac-params" class="section">
+ <h4>AesCmacParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-AesCmacParams">AesCmacParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The length, in bits, of the MAC.</span>
+[EnforceRange] unsigned short <dfn id="dfn-AesCmacParams-length">length</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="aes-cmac-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Sign</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>length</var> equal the <a href="#dfn-AesCmacParams-length">length</a>
+ member of <var>normalizedAlgorithm</var>, if present, and 128 otherwise.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>length</var> is zero or greater than 128,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>mac</var> be the result of performing the MAC Generation
+ operation described in Section 6.2 of
+ NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>] using AES as the block
+ cipher, <var>length</var> as the value of the MAC length parameter,
+ <var>Tlen</var>, and <var>message</var> as the message, <var>M</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>mac</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Verify</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>length</var> equal the <a href="#dfn-AesCmacParams-length">length</a>
+ member of <var>normalizedAlgorithm</var>, if present, and 128 otherwise.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>length</var> is zero or greater than 128,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>output</var> be the result of performing the MAC Verification
+ operation described in Section 6.3 of
+ NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>] using AES as the block
+ cipher, <var>length</var> as the value of the MAC length parameter,
+ <var>Tlen</var>, <var>message</var> as the message, <var>M</var> and
+ <var>signature</var> as the received MAC, <var>T'</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return true if <var>output</var> is VALID and false otherwise.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not equal to one of
+ 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not
+ <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an AES key of length
+ equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CMAC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ to <code>"oct"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128CMAC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192CMAC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256CMAC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
+ object representing an AES key with value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CMAC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128CMAC"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192CMAC"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256CMAC"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If any of the members of
+ <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
+ <var>normalizedDerivedKeyAlgorithm</var>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div id="aes-gcm" class="section">
+ <h3>AES-GCM</h3>
+ <div id="aes-gcm-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-GCM"</code> algorithm identifier is used to perform
+ authenticated encryption and decryption using AES in Galois/Counter Mode mode,
+ as described in NIST SP 800-38D [<a href="#SP800-38D">SP800-38D</a>].
+ </p>
+ </div>
+ <div id="aes-gcm-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-GCM"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>encrypt</td>
+ <td><a href="#dfn-AesGcmParams">AesGcmParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>decrypt</td>
+ <td><a href="#dfn-AesGcmParams">AesGcmParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="aes-gcm-params" class="section">
+ <h4>AesGcmParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-AesGcmParams">AesGcmParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The initialization vector to use. May be up to 2^64-1 bytes long.</span>
+CryptoOperationData <dfn id="dfn-AesGcmParams-iv">iv</dfn>;
+<span class="comment">// The additional authentication data to include.</span>
+CryptoOperationData? <dfn id="dfn-AesGcmParams-additionalData">additionalData</dfn>;
+<span class="comment">// The desired length of the authentication tag. May be 0 - 128.</span>
+[EnforceRange] octet? <dfn id="dfn-AesGcmParams-tagLength">tagLength</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="aes-gcm-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Encrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>plaintext</var> has a length greater than 2^39 - 256
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> has a length greater than 2^64 - 1
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member
+ of <var>normalizedAlgorithm</var> is present, is not null and has a length
+ greater than 2^64 - 1 bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var> is not present or is null:</dt>
+ <dd>Let <var>tagLength</var> be 128.</dd>
+ <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var> is one of 32, 64, 96, 104, 112, 120 or 128:</dt>
+ <dd>Let <var>tagLength</var> be equal to the
+ <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var></dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>paddedPlaintext</var> be the result of adding padding octets to
- <var>ciphertext</var> according to the procedure defined in Section 10.3
- of RFC 2315 [<a href="#RFC2315">RFC2315</a>], step 2, with a value of
- <var>k</var> of 16.
- </p>
- </li>
- <li>
- <p>
- Let <var>ciphertext</var> be the result of performing the CBC Encryption
- operation described in Section 6.2 of NIST SP 800-38A [<a
- href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
- href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-AesCbcParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter and <a
- href="#concept-contents-of-arraybuffer">the contents of
- <var>paddedPlaintext</var></a> as the input plaintext.
- </p>
- </li>
- <li>
- <p>
- Return <var>ciphertext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Decrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCbcParams">AesCbcParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-cbc-params">AesCbcParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCbcParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>paddedPlaintext</var> be the result of performing the CBC Decryption
- operation described in Section 6.2 of NIST SP 800-38A [<a
- href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
- href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-AesCbcParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter and <a
- href="#concept-contents-of-arraybuffer">the contents of
- <var>ciphertext</var></a> as the input ciphertext.
- </p>
- </li>
- <li>
- <p>
- Let <var>p</var> be the value of the last octet of <var>paddedPlaintext</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>p</var> is zero or greater than 16, or if any of the last <var>p</var>
- octets of <var>paddedPlaintext</var> have a value which is not <var>p</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>plaintext</var> be the result of removing <var>p</var> octets from
- the end of <var>paddedPlaintext</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>plaintext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>additionalData</var> be <a
+ href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-AesGcmParams-additionalData">additionalData</a> member of
+ <var>normalizedAlgorithm</var> if present and not null and the empty octet
+ string otherwise.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>C</var> and <var>T</var> be the outputs that result from performing
+ the Authenticated Encryption Function described in Section 7.1 of NIST SP
+ 800-38D [<a href="#SP800-38D">SP800-38D</a>] using AES as the block cipher, <a
+ href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-AesGcmParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter, <a
+ href="#concept-contents-of-arraybuffer">the contents of
+ <var>additionalData</var></a> as the <var>A</var> input parameter,
+ <var>tagLength</var> as the <var>t</var> pre-requisite and <a
+ href="#concept-contents-of-arraybuffer">the contents of
+ <var>plaintext</var></a> as the input plaintext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return a new ArrayBuffer containing <var>C</var> | <var>T</var>
+ where '|' denotes concatenation.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Decrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var> is not present or null:</dt>
+ <dd>Let <var>tagLength</var> be 128.</dd>
+ <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var> is one of 32, 64, 96, 104, 112, 120 or 128:</dt>
+ <dd>Let <var>tagLength</var> be equal to the
+ <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var></dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an AES key of length
- equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CBC"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>plaintext</var> has a length less than <var>tagLength</var> bits,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> has a length greater than 2^64 - 1
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member
+ of <var>normalizedAlgorithm</var> is present, is not null and has a length
+ greater than 2^64 - 1
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>tag</var> be the last <var>tagLength</var> bits of
+ <var>ciphertext</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>actualCiphertext</var> be the result of removing the last <var>tagLength</var> bits
+ from <var>ciphertext</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>additionalData</var> be <a
+ href="#concept-contents-of-arraybuffer">the contents</a> of the <a
+ href="#dfn-AesGcmParams-additionalData">additionalData</a> member of
+ <var>normalizedAlgorithm</var> if present and not null and the empty octet
+ string otherwise.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the Authenticated Decryption Function described in Section 7.2 of NIST
+ SP 800-38D [<a href="#SP800-38D">SP800-38D</a>] using AES as the block cipher,
+ <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-AesGcmParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter, <a
+ href="#concept-contents-of-arraybuffer">the contents of
+ <var>additionalData</var></a> as the <var>A</var> input parameter,
+ <var>tagLength</var> as the <var>t</var> pre-requisite, <a
+ href="#concept-contents-of-arraybuffer">the contents of
+ <var>actualCiphertext</var></a> as the input ciphertext, <var>C</var> and <a
+ href="#concept-contents-of-arraybuffer">the contents of <var>tag</var></a> as
+ the authentication tag, <var>T</var>.
+ </p>
+ <dl class="switch">
+ <dt>If the result of the algorithm is the indication of inauthenticity,
+ "<var>FAIL</var>":</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>Let <var>plaintext</var> be the output <var>P</var> of the Authenticated
+ Decryption Function.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return a new ArrayBuffer containing <var>plaintext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not equal to one of
+ 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an AES key of length
+ equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-GCM"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"oct"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128GCM"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192GCM"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256GCM"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
+ object representing an AES key with value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-GCM"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128GCM"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192GCM"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256GCM"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- to <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128CBC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192CBC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256CBC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="aes-cfb" class="section">
+ <h3>AES-CFB</h3>
+ <div id="aes-cfb-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-CFB-8"</code> algorithm identifier is used to perform
+ encryption and decryption using AES in Cipher Feedback mode, specifically CFB-8,
+ as described in Section 6.3 of NIST SP 800-38A
+ [<a href="#SP800-38A">SP800-38A</a>].
+ </p>
+ </div>
+ <div id="aes-cfb-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-CFB-8"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>encrypt</td>
+ <td><a href="#dfn-AesCfbParams">AesCfbParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>decrypt</td>
+ <td><a href="#dfn-AesCfbParams">AesCfbParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="aes-cfb-params" class="section">
+ <h4>AesCfbParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-AesCfbParams">AesCfbParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The initialization vector. <span class="RFC2119">MUST</span> be 16 bytes.</span>
+CryptoOperationData <dfn id="dfn-AesCfbParams-iv">iv</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="aes-cfb-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Encrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCfbParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16 bytes, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ciphertext</var> be the result of performing the CFB Encryption
+ operation described in Section 6.3 of NIST SP 800-38A [<a
+ href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
+ href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-AesCfbParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter, the value 8 as the input parameter
+ <var>s</var>, and <a href="#concept-contents-of-arraybuffer">the contents
+ of<var>plaintext</var></a> as the input plaintext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>ciphertext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Decrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCfbParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16 bytes, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>plaintext</var> be the result of performing the CFB Decryption
+ operation described in Section 6.3 of NIST SP 800-38A [<a
+ href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
+ href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-AesCfbParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter, the the value 8 as the input parameter
+ <var>s</var>, and <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>ciphertext</var></a> as the input ciphertext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>plaintext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not equal to one of 128, 192 or 256, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not one of
+ <code>"encrypt"</code>, <code>"decrypt"</code>, <code>"wrapKey"</code> or
+ <code>"unwrapKey"</code>, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an AES key of length equal to the <a
+ href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CFB-8"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"oct"</code>,
then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
- object representing an AES key with value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CBC"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128CBC"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192CBC"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256CBC"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="aes-cmac" class="section">
- <h3>AES-CMAC</h3>
- <div id="aes-cmac-description" class="section">
- <h4>Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"AES-CMAC"</code> algorithm identifier is used to perform
- message authentication using AES with a cipher-based MAC, as
- described in NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>].
- </p>
- </div>
- <div id="aes-cmac-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-CMAC"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>sign</td>
- <td><a href="#dfn-AesCmacParams">AesCmacParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>verify</td>
- <td><a href="#dfn-AesCmacParams">AesCmacParams</a></td>
- <td>boolean</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="aes-cmac-params" class="section">
- <h4>AesCmacParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-AesCmacParams">AesCmacParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The length, in bits, of the MAC.</span>
- [EnforceRange] unsigned short <dfn id="dfn-AesCmacParams-length">length</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="aes-cmac-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Sign</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>length</var> equal the <a href="#dfn-AesCmacParams-length">length</a>
- member of <var>normalizedAlgorithm</var>, if present, and 128 otherwise.
- </p>
- </li>
- <li>
- <p>
- If <var>length</var> is zero or greater than 128,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>mac</var> be the result of performing the MAC Generation
- operation described in Section 6.2 of
- NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>] using AES as the block
- cipher, <var>length</var> as the value of the MAC length parameter,
- <var>Tlen</var>, and <var>message</var> as the message, <var>M</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>mac</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Verify</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCmacParams">AesCmacParams</a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>length</var> equal the <a href="#dfn-AesCmacParams-length">length</a>
- member of <var>normalizedAlgorithm</var>, if present, and 128 otherwise.
- </p>
- </li>
- <li>
- <p>
- If <var>length</var> is zero or greater than 128,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>output</var> be the result of performing the MAC Verification
- operation described in Section 6.3 of
- NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>] using AES as the block
- cipher, <var>length</var> as the value of the MAC length parameter,
- <var>Tlen</var>, <var>message</var> as the message, <var>M</var> and
- <var>signature</var> as the received MAC, <var>T'</var>.
- </p>
- </li>
- <li>
- <p>
- Return true if <var>output</var> is VALID and false otherwise.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an AES key of length
- equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CMAC"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128CFB8"</code>,
then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- to <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192CFB8"</code>,
then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128CMAC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192CMAC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256CMAC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256CFB8"</code>,
then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
- object representing an AES key with value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CMAC"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128CMAC"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192CMAC"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256CMAC"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
- <div id="aes-gcm" class="section">
- <h3>AES-GCM</h3>
- <div id="aes-gcm-description" class="section">
- <h4>Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"AES-GCM"</code> algorithm identifier is used to perform
- authenticated encryption and decryption using AES in Galois/Counter Mode mode,
- as described in NIST SP 800-38D [<a href="#SP800-38D">SP800-38D</a>].
- </p>
- </div>
- <div id="aes-gcm-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-GCM"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>encrypt</td>
- <td><a href="#dfn-AesGcmParams">AesGcmParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>decrypt</td>
- <td><a href="#dfn-AesGcmParams">AesGcmParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="aes-gcm-params" class="section">
- <h4>AesGcmParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-AesGcmParams">AesGcmParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The initialization vector to use. May be up to 2^64-1 bytes long.</span>
- CryptoOperationData <dfn id="dfn-AesGcmParams-iv">iv</dfn>;
- <span class="comment">// The additional authentication data to include.</span>
- CryptoOperationData? <dfn id="dfn-AesGcmParams-additionalData">additionalData</dfn>;
- <span class="comment">// The desired length of the authentication tag. May be 0 - 128.</span>
- [EnforceRange] octet? <dfn id="dfn-AesGcmParams-tagLength">tagLength</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="aes-gcm-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Encrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesGcmParams">AesGcmParams</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
- <a href="#aes-gcm-params">AesGcmParams</a> is not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>plaintext</var> has a length greater than 2^39 - 256
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> has a length greater than 2^64 - 1
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member
- of <var>normalizedAlgorithm</var> is present, is not null and has a length
- greater than 2^64 - 1 bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var> is not present or is null:</dt>
- <dd>Let <var>tagLength</var> be 128.</dd>
- <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var> is one of 32, 64, 96, 104, 112, 120 or 128:</dt>
- <dd>Let <var>tagLength</var> be equal to the
- <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var></dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>additionalData</var> be <a
- href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-AesGcmParams-additionalData">additionalData</a> member of
- <var>normalizedAlgorithm</var> if present and not null and the empty octet
- string otherwise.
- </p>
- </li>
- <li>
- <p>
- Let <var>C</var> and <var>T</var> be the outputs that result from performing
- the Authenticated Encryption Function described in Section 7.1 of NIST SP
- 800-38D [<a href="#SP800-38D">SP800-38D</a>] using AES as the block cipher, <a
- href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-AesGcmParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter, <a
- href="#concept-contents-of-arraybuffer">the contents of
- <var>additionalData</var></a> as the <var>A</var> input parameter,
- <var>tagLength</var> as the <var>t</var> pre-requisite and <a
- href="#concept-contents-of-arraybuffer">the contents of
- <var>plaintext</var></a> as the input plaintext.
- </p>
- </li>
- <li>
- <p>
- Return a new ArrayBuffer containing <var>C</var> | <var>T</var>
- where '|' denotes concatenation.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Decrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesGcmParams">AesGcmParams</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
- <a href="#aes-gcm-params">AesGcmParams</a> is not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var> is not present or null:</dt>
- <dd>Let <var>tagLength</var> be 128.</dd>
- <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var> is one of 32, 64, 96, 104, 112, 120 or 128:</dt>
- <dd>Let <var>tagLength</var> be equal to the
- <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var></dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>plaintext</var> has a length less than <var>tagLength</var> bits,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> has a length greater than 2^64 - 1
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member
- of <var>normalizedAlgorithm</var> is present, is not null and has a length
- greater than 2^64 - 1
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>tag</var> be the last <var>tagLength</var> bits of
- <var>ciphertext</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>actualCiphertext</var> be the result of removing the last <var>tagLength</var> bits
- from <var>ciphertext</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>additionalData</var> be <a
- href="#concept-contents-of-arraybuffer">the contents</a> of the <a
- href="#dfn-AesGcmParams-additionalData">additionalData</a> member of
- <var>normalizedAlgorithm</var> if present and not null and the empty octet
- string otherwise.
- </p>
- </li>
- <li>
- <p>
- Perform the Authenticated Decryption Function described in Section 7.2 of NIST
- SP 800-38D [<a href="#SP800-38D">SP800-38D</a>] using AES as the block cipher,
- <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-AesGcmParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter, <a
- href="#concept-contents-of-arraybuffer">the contents of
- <var>additionalData</var></a> as the <var>A</var> input parameter,
- <var>tagLength</var> as the <var>t</var> pre-requisite, <a
- href="#concept-contents-of-arraybuffer">the contents of
- <var>actualCiphertext</var></a> as the input ciphertext, <var>C</var> and <a
- href="#concept-contents-of-arraybuffer">the contents of <var>tag</var></a> as
- the authentication tag, <var>T</var>.
- </p>
- <dl class="switch">
- <dt>If the result of the algorithm is the indication of inauthenticity,
- "<var>FAIL</var>":</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>
- </dd>
- <dt>Otherwise:</dt>
- <dd>Let <var>plaintext</var> be the output <var>P</var> of the Authenticated
- Decryption Function.</dd>
- </dl>
- </li>
- <li>
- <p>
- Return a new ArrayBuffer containing <var>plaintext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an AES key of length
- equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-GCM"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128GCM"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192GCM"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256GCM"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
- object representing an AES key with value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-GCM"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128GCM"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192GCM"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256GCM"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
+ object representing an AES key with value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CFB-8"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128CFB8"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192CFB8"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256CFB8"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> property of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> property of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="aes-kw" class="section">
+ <h3>AES-KW</h3>
+ <div id="aes-kw-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-KW"</code> algorithm identifier is used to perform
+ key wrapping using AES, as
+ described in [<a href="#rfc3394">RFC3394</a>].
+ </p>
+ </div>
+ <div id="aes-kw-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-KW"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>wrapKey</td>
+ <td>None</td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>unwrapKey</td>
+ <td>None</td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="aes-kw-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Wrap Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>plaintext</var> is not a multiple of 64 bits in length,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ciphertext</var> be the result of performing the Key Wrap
+ operation described in Section 2.2.1 of [<a href="#rfc3394">RFC3394</a>]
+ with <var>plaintext</var> as the plaintext to be wrapped and using the default
+ Initial Value defined in Section 2.2.3.1 of the same document.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>ciphertext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Unwrap Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>plaintext</var> be the result of performing the Key Unwrap
+ operation described in Section 2.2.2 of [<a href="#rfc3394">RFC3394</a>] with
+ <var>ciphertext</var> as the input ciphertext and using the default Initial
+ Value defined in Section 2.2.3.1 of the same document.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the Key Unwrap operation returns an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>plaintext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> property of
+ <var>normalizedAlgorithm</var> is not equal to one of 128, 192 or 256, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not one of
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-KW"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> property of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ one of <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"oct"</code>,
then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128KW"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192KW"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256KW"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>. </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing an AES key with value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-KW"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128KW"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192KW"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256KW"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="hmac" class="section">
+ <h3>HMAC</h3>
+ <div id="hmac-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>HMAC</code> algorithm calculates and verifies hash-based message
+ authentication codes according to [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>].
+ </p>
+ </div>
+ <div id="hmac-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"HMAC"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sign</td>
+ <td>None</td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>verify</td>
+ <td>None</td>
+ <td>boolean</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-HmacKeyGenParams">HmacKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-HmacImportParams">HmacImportParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-HmacDerivedKeyParams">HmacDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="hmac-importparams" class="section">
+ <h4>HmacImportParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-HmacImportParams">HmacImportParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The inner hash function to use.</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-HmacImportParams-hash">hash</dfn>;
+<span class="comment">// The length (in bits) of the key.</span>
+[EnforceRange] unsigned long <dfn id="dfn-HmacImportParams-length">length</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="HmacKeyAlgorithm-dictionary" class="section">
+ <h4>HmacKeyAlgorithm dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
+<span class="comment">// The inner hash function to use.</span>
+KeyAlgorithm <dfn id="dfn-HmacKeyAlgorithm-hash">hash</dfn>;
+<span class="comment">// The length (in bits) of the key.</span>
+unsigned long <dfn id="dfn-HmacKeyAlgorithm-length">length</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="hmac-keygen-params" class="section">
+ <h4>HmacKeyGenParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-HmacKeyGenParams">HmacKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The inner hash function to use.</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-HmacKeyGenParams-hash">hash</dfn>;
+<span class="comment">// The length (in bits) of the key to generate. If unspecified, the
+// recommended length will be used, which is the size of the associated hash function's block
+// size.</span>
+[EnforceRange] unsigned long <dfn id="dfn-HmacKeyGenParams-length">length</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="hmac-derivedkey-params" class="section">
+ <h4>HmacDerivedKeyParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-HmacDerivedKeyParams">HmacDerivedKeyParams</dfn> : <a href="#dfn-HmacImportParams">HmacImportParams</a> {
+<span class="comment">// The length (in bits) of the key to generate. If unspecified, the
+// recommended length will be used, which is the size of the associated hash function's block
+// size.</span>
+[EnforceRange] unsigned long <dfn id="dfn-HmacDerivedKeyParams-length">length</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="hmac-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Sign</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>mac</var> be the result of performing the MAC Generation operation
+ described in Section 4 of [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using
+ the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
+ internal slot of <var>key</var>, the hash function identified by the <a
+ href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> and <var>message</var> as the input data <var>text</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>mac</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Verify</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>mac</var> be the result of performing the MAC Generation operation
+ described in Section 4 of [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using
+ the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
+ internal slot of <var>key</var>, the hash function identified by the <a
+ href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> and <var>message</var> as the input data <var>text</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return true if <var>mac</var> is equal to <var>signature</var> and false
+ otherwise.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not present:
+ </dt>
+ <dd>
+ Let <var>length</var> be the block size in bits of the hash function
+ identified by the <a href="#dfn-HmacKeyGenParams-hash">hash</a> member
+ of <var>normalizedAlgorithm</var>.
+ </dd>
+ <dt>
+ Otherwise, if the <a href="#dfn-HmacKeyGenParams-length">length</a>
+ member of <var>normalizedAlgorithm</var> is non-zero:
+ </dt>
+ <dd>
+ Let <var>length</var> be equal to the
+ <a href="#dfn-HmacKeyGenParams-length">length</a>
+ member of <var>normalizedAlgorithm</var>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not <code>"sign"</code> or
+ <code>"verify"</code>, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate a key of length <var>length</var> bits.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"HMAC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a new
+ <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to equal the <a href="#dfn-Algorithm-name">name</a>
+ member of the <a href="#dfn-HmacKeyGenParams-hash">hash</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute
+ of <var>algorithm</var> to <var>hash</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var> is present and has a
+ <a href="#dfn-Algorithm-name">name</a> member:
+ </dt>
+ <dd>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to equal the <a href="#dfn-Algorithm-name">name</a>
+ member of the <a href="#dfn-HmacImportParams-hash">hash</a>
+ member of <var>normalizedAlgorithm</var>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"oct"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var> is present and has a
+ <a href="#dfn-Algorithm-name">name</a> member:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to equal the <a
+ href="#dfn-Algorithm-name">name</a> member of the <a
+ href="#dfn-HmacImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is
+ <code>"SHA-1"</code>:
+ </dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present
+ and is not <code>"HS1"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is
+ <code>"SHA-256"</code>:
+ </dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present
+ and is not <code>"HS256"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is
+ <code>"SHA-384"</code>:
+ </dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present
+ and is not <code>"HS384"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is
+ <code>"SHA-512"</code>:
+ </dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present
+ and is not <code>"HS512"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <code>alg</code> field of <var>jwk</var> is not present,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is
+ <code>"HS1"</code>:
+ </dt>
+ <dd>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to <code>"SHA-1"</code>.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is
+ to <code>"HS256"</code>:
+ </dt>
+ <dd>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to <code>"SHA-256"</code>.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is
+ <code>"HS384"</code>:
+ </dt>
+ <dd>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to <code>"SHA-384"</code>.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is
+ <code>"HS512"</code>:
+ </dt>
+ <dd>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to <code>"SHA-512"</code>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"sign"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>length</var> be equivalent to the length, in octets, of
+ <var>data</var>, multiplied by 8.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>length</var> is zero
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacImportParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is present:
+ </dt>
+ <dd>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacImportParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is greater than <var>length</var>:
+ </dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-HmacImportParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>, is less than or equal to
+ <var>length</var> minus eight:
+ </dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>
+ Otherwise:
+ </dt>
+ <dd>
+ Set <var>length</var> equal to the <a href="#dfn-HmacImportParams-length">
+ length</a> member of <var>normalizedAlgorithm</var>.
+ </dd>
+ </dl>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
+ object representing an HMAC key with the first <var>length</var>
+ bits of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"HMAC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-HmacKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to <var>length</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of
+ <var>algorithm</var> to <var>hash</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a
+ href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be the
+ <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of
+ <var>algorithm</var>.
+ </p>
+ </li>
+
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is <code>"SHA-1"</code>:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"HS1"</code>.</dd>
+ <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is <code>"SHA-256"</code>:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"HS256"</code>.</dd>
+ <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is <code>"SHA-384"</code>:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"HS384"</code>.</dd>
+ <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is <code>"SHA-512"</code>:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"HS512"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
+ href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not present:
+ </dt>
+ <dd>
+ Let <var>length</var> be the block size in bytes of the hash function
+ identified by the <a href="#dfn-HmacImportParams-hash">hash</a> member
+ of <var>normalizedDerivedKeyAlgorithm</var>.
+ </dd>
+ <dt>
+ Otherwise, if the <a href="#dfn-HmacDerivedKeyParams-length">length</a>
+ member of <var>normalizedDerivedKeyAlgorithm</var> is non-zero:
+ </dt>
+ <dd>
+ Let <var>length</var> be equal to the
+ <a href="#dfn-HmacDerivedKeyParams-length">length</a>
+ member of <var>normalizedDerivedKeyAlgorithm</var>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>length</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div id="dh" class="section">
+ <h3>Diffie-Hellman</h3>
+ <div id="dh-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ This describes using Diffie-Hellman for key generation and key agreement, as specified
+ by <a href="#PKCS3">PKCS #3</a>.
+ </p>
+ </div>
+ <div id="dh-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"DH"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-DhKeyGenParams">DhKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>deriveBits</td>
+ <td><a href="#dfn-DhKeyDeriveParams">DhKeyDeriveParams</a></td>
+ <td>Octet string</td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-DhImportKeyParams">DhImportKeyParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="dh-DhKeyGenParams" class="section">
+ <h4>DhKeyGenParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-DhKeyGenParams">DhKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The prime p.</span>
+BigInteger <dfn id="dfn-DhKeyGenParams-prime">prime</dfn>;
+<span class="comment">// The base g.</span>
+BigInteger <dfn id="dfn-DhKeyGenParams-generator">generator</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="dh-DhKeyAlgorithm" class="section">
+ <h4>DhKeyAlgorithm dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-DhKeyAlgorithm">DhKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
+<span class="comment">// The prime p.</span>
+BigInteger <dfn id="dfn-DhKeyAlgorithm-prime">prime</dfn>;
+<span class="comment">// The base g.</span>
+BigInteger <dfn id="dfn-DhKeyAlgorithm-generator">generator</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="dh-DhKeyDeriveParams" class="section">
+ <h4>DhKeyDeriveParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-DhKeyDeriveParams">DhKeyDeriveParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The peer's public value.</span>
+<a href="#dfn-CryptoKey">CryptoKey</a> <dfn id="dfn-DhKeyDeriveParams-public">public</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="dh-DhImportKeyParams" class="section">
+ <h4>DhImportKeyParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-DhImportKeyParams">DhImportKeyParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The prime p.</span>
+BigInteger <dfn id="dfn-DhImportKeyParams-prime">prime</dfn>;
+<span class="comment">// The base g.</span>
+BigInteger <dfn id="dfn-DhImportKeyParams-generator">generator</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="dh-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains a value which is not
+ one of <code>"deriveKey"</code> or <code>"deriveBits"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate a Diffie-Hellman key pair, as defined in Section 7 of
+ [<a href="#PKCS3">PKCS #3</a>], with prime, <var>p</var>, and base,
+ <var>g</var>, as specified in the
+ <a href="#dfn-DhKeyGenParams-prime">prime</a> and
+ <a href="#dfn-DhKeyGenParams-generator">generator</a> properties of
+ <var>normalizedAlgorithm</var>, respectively.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>algorithm</var> to <code>"DH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-DhKeyGenParams-prime">prime</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-DhKeyGenParams-generator">generator</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the empty list.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to be <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to be <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object, as
+ defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Derive Bits</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be the
+ <a href="#dfn-DhKeyDeriveParams-public">public</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> is not <code>"DH"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> is not equal to the <a
+ href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
+ named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of the
+ [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> is not equal to the <a
+ href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
+ named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the Diffie-Hellman Phase II algorithm as specified in Section 8 of [<a
+ href="#PKCS3">PKCS #3</a>] with <var>key</var> as the DH private value
+ <var>x</var> and the Diffie-Hellman public value represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of the <a
+ href="#dfn-DhKeyDeriveParams-public">public</a> member of
+ <var>normalizedAlgorithm</var> as the other's public value <var>PV'</var>.
+ </p>
+ <dl class="switch">
+ <dt>If performing the operation results in an error:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ Let <var>secret</var> be the output of the DH Phase II, <var>SK</var>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the length of <var>secret</var> in bits is less than
+ <var>length</var>:
+ </dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>Return the first <var>length</var> bits of <var>secret</var>.</dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <dl class="switch">
+ <dt>
+ If <var>format</var> is <code>"raw"</code>:
+ </dt>
+ <dd>
+ <div class="ednote">
<p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var>.
+ Raw import of private values is presently not supported.
</p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="aes-cfb" class="section">
- <h3>AES-CFB</h3>
- <div id="aes-cfb-description" class="section">
- <h4>Description</h4>
- <p class="norm">This section is non-normative.</p>
+ </div>
+ <ol>
+ <li>
+ <p>
+ If <var>extractable</var> is false,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>PV</var> be the integer which results from interpreting the
+ octets of <var>keyData</var> as an unsigned big integer with most
+ significant octet first.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing a Diffie-Hellman public key with public value <var>PV</var>
+ and with prime, <var>p</var> and base, <var>g</var> equal to the <a
+ href="#dfn-DhImportKeyParams-prime">prime</a> and <a
+ href="#dfn-DhImportKeyParams-generator">generator</a> properties of
+ <var>normalizedAlgorithm</var> respectively.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"public"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a
+ href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-Algorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"DH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
+ <var>algorithm</var> to equal the <a
+ href="#dfn-DhImportKeyParams-prime">prime</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
+ <var>algorithm</var> to equal the <a
+ href="#dfn-DhImportKeyParams-generator">generator</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
+ of <var>key</var> to <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ If <var>format</var> is <code>"spki"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the <a
+ href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a> algorithm
+ over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is not
+ equivalent to the <code>dhKeyAgreement</code> OID defined in Section 9 of
+ [<a href="#PKCS3">PKCS #3</a>], then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the <code>algorithm</code>
+ AlgorithmIdentifier field of <var>spki</var> is absent, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not an instance of the <code>DHParameter</code>
+ ASN.1 type defined in Section 9 of <a href="#PKCS3">PKCS #3</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the Diffie-Hellman public key obtained by parsing the
+ <code>subjectPublicKey</code> field of <var>spki</var> as an ASN.1
+ INTEGER.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"public"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a
+ href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>algorithm</var> to <code>"DH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
+ <var>algorithm</var> to a new <code>BigInteger</code> equal to the
+ octet string encoding of the <code>prime</code> field of
+ <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
+ <var>algorithm</var> to a new <code>BigInteger</code> equal to the
+ octet string encoding of the <code>base</code> field of
+ <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
+ of <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ If <var>format</var> is <code>"pkcs8"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains a value which is not one of
+ <code>"deriveKey"</code> or <code>"deriveBits"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>algorithm</code> AlgorithmIdentifier field of
+ <var>privateKeyInfo</var> is not equivalent to the
+ <code>dhKeyAgreement</code> OID defined in Section 9 of [<a
+ href="#PKCS3">PKCS #3</a>], then <a href="#concept-return-an-error">return
+ an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field of
+ <var>privateKeyInfo</var> is absent, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field of
+ <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not an instance of the <code>DHParameter</code>
+ ASN.1 type defined in Section 9 of <a href="#PKCS3">PKCS #3</a>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the Diffie-Hellman private key obtained by parsing the
+ <code>privateKey</code> field of <var>privateKeyInfo</var> as an ASN.1
+ INTEGER.
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"private"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>algorithm</var> to <code>"DH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
+ <var>algorithm</var> to a new <code>BigInteger</code> equal to the
+ octet string encoding of the <code>prime</code> field of
+ <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
+ <var>algorithm</var> to a new <code>BigInteger</code> equal to the
+ octet string encoding of the <code>base</code> field of
+ <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
+ of <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>format</var> is <code>"raw"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is <code>"public"</code>:
+ </dt>
+ <dd>
+ Let <var>data</var> be the Public Value, <var>PV</var>, associated
+ with <var>key</var> as specified in Section 7 of [<a
+ href="#PKCS3">PKCS #3</a>].
+ </dd>
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is <code>"private"</code>:
+ </dt>
+ <dd>
+ Let <var>data</var> be the octet string that represents the private
+ value <var>x</var> associated with <var>key</var> as a big integer,
+ most significant octet first.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ If <var>format</var> is <code>"spki"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a
+ href="#concept-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithmIdentifier</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 structure with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the
+ <code>dhKeyAgreement</code> OID defined in Section 9 of <a
+ href="#PKCS3">PKCS #3</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>DHParams</code> ASN.1 structure defined in Section 9 of
+ <a href="#PKCS3">PKCS #3</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>prime</var> field to an ASN.1 INTEGER that is
+ equivalent to the <a
+ href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>base</var> field to an ASN.1 INTEGER that is
+ equivalent to the <a
+ href="#dfn-DhKeyAlgorithm-generator">generator</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> to an ASN.1 INTEGER that
+ corresponds to the Diffie-Hellman public value represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ If <var>format</var> is <code>"pkcs8"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"private"</code>, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a
+ href="#concept-encode-a-privateKeyInfo">encoding a
+ privateKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to a
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 structure with
+ the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the
+ <code>dhKeyAgreement</code> OID defined in Section 9 of <a
+ href="#PKCS3">PKCS #3</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>DHParams</code> ASN.1 structure defined in Section 9 of
+ <a href="#PKCS3">PKCS #3</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>prime</var> field to an ASN.1 INTEGER that is
+ equivalent to the <a
+ href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
+ the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>base</var> field to an ASN.1 INTEGER that is
+ equivalent to the <a
+ href="#dfn-DhKeyAlgorithm-generator">generator</a>
+ attribute of the [[<a
+ href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to an ASN.1 INTEGER that
+ corresponds to the Diffie-Hellman private value represented by
+ [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div id="sha" class="section">
+ <h3>SHA</h3>
+ <div id="sha-description" class="section">
+ <h4>Description</h4>
+ <p>
+ This describes the SHA-1 and SHA-2 families, as specified by
+ [<a href="#FIPS180-4">FIPS PUB 180-4</a>].
+ </p>
+ </div>
+ <div id="sha-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The following algorithms are added as <a href="#recognized-algorithm-name">
+ recognized algorithm names</a>:
+ </p>
+ <dl>
+ <dt id="alg-sha-1"><code>"SHA-1"</code></dt>
+ <dd>The SHA-1 algorithm as specified in Section 6.1</dd>
+ <dt id="alg-sha-256"><code>"SHA-256"</code></dt>
+ <dd>The SHA-256 algorithm as specified in Section 6.2</dd>
+ <dt id="alg-sha-384"><code>"SHA-384"</code></dt>
+ <dd>The SHA-384 algorithm as specified in Section 6.5</dd>
+ <dt id="alg-sha-512"><code>"SHA-512"</code></dt>
+ <dd>The SHA-512 algorithm as specified in Section 6.4</dd>
+ </dl>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>digest</td>
+ <td>None</td>
+ <td>ArrayBuffer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="sha-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Digest</dt>
+ <dd>
+ <ol>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>normalizedAlgorithm</var> is a cases-sensitive string match for
+ <code>"SHA-1"</code>:
+ </dt>
+ <dd>
+ Let <var>result</var> be the result of performing the SHA-1 hash function
+ defined in Section 6.1 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
+ <var>message</var> as the input message, <var>M</var>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>normalizedAlgorithm</var> is a cases-sensitive string match for
+ <code>"SHA-256"</code>:
+ </dt>
+ <dd>
+ Let <var>result</var> be the result of performing the SHA-256 hash function
+ defined in Section 6.2 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
+ <var>message</var> as the input message, <var>M</var>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>normalizedAlgorithm</var> is a cases-sensitive string match for
+ <code>"SHA-384"</code>:
+ </dt>
+ <dd>
+ Let <var>result</var> be the result of performing the SHA-384 hash function
+ defined in Section 6.5 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
+ <var>message</var> as the input message, <var>M</var>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>normalizedAlgorithm</var> is a cases-sensitive string match for
+ <code>"SHA-512"</code>:
+ </dt>
+ <dd>
+ Let <var>result</var> be the result of performing the SHA-1 hash function
+ defined in Section 6.4 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
+ <var>message</var> as the input message, <var>M</var>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return a new ArrayBuffer containing <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div id="concatkdf" class="section">
+ <h3>Concat KDF</h3>
+ <div id="concatkdf-description" class="section">
+ <h4>Description</h4>
+ <p>
+ The <code>"CONCAT"</code> algorithm identifier is used to perform key derivation
+ using the key derivation algorithm defined in Section 5.8.1 of NIST SP 800-56A
+ [<a href="#SP800-56A">SP800-56A</a>].
+ </p>
+ </div>
+ <div id="concatkdf-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"CONCAT"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>deriveBits</td>
+ <td><a href="#dfn-ConcatParams">ConcatParams</a></td>
+ <td>Octet string</td>
+ </tr>
+ <tr>
+ <td>Import key</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>Get key length</td>
+ <td>None</td>
+ <td>Integer or null</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="concat-params" class="section">
+ <h4>ConcatParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-ConcatParams">ConcatParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The digest method to use to derive the keying material.</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-ConcatParams-hash">hash</dfn>;
+
+<span class="comment">// A bit string corresponding to the AlgorithmId field of the OtherInfo parameter.</span>
+<span class="comment">// The AlgorithmId indicates how the derived keying material will be parsed and for which</span>
+<span class="comment">// algorithm(s) the derived secret keying material will be used.</span>
+CryptoOperationData <dfn id="dfn-ConcatParams-algorithmId">algorithmId</dfn>;
+<span class="comment">// A bit string that corresponds to the PartyUInfo field of the OtherInfo parameter.</span>
+CryptoOperationData <dfn id="dfn-ConcatParams-partyUInfo">partyUInfo</dfn>;
+<span class="comment">// A bit string that corresponds to the PartyVInfo field of the OtherInfo parameter.</span>
+CryptoOperationData <dfn id="dfn-ConcatParams-partyVInfo">partyVInfo</dfn>;
+<span class="comment">// An optional bit string that corresponds to the SuppPubInfo field of the OtherInfo parameter.</span>
+CryptoOperationData? <dfn id="dfn-ConcatParams-publicInfo">publicInfo</dfn>;
+<span class="comment">// An optional bit string that corresponds to the SuppPrivInfo field of the OtherInfo parameter.</span>
+CryptoOperationData? <dfn id="dfn-ConcatParams-privateInfo">privateInfo</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="concat-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Derive Bits</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>secret</var> be the result of performing the Concatenation Key
+ Derivation Function defined in Section 5.8.1 of
+ [<a href="#SP800-56A">SP800-56A</a>] with <var>length</var> as
+ <var>keydatalen</var>, the hash function identified by the
+ <a href="#dfn-ConcatParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var> as <var>H</var>, the
+ <a href="#dfn-ConcatParams-algorithmId">algorithmId</a> member of
+ <var>normalizedAlgorithm</var> as <var>AlgorithmID</var>, the
+ <a href="#dfn-ConcatParams-partyUInfo">partyUInfo</a> member of
+ <var>normalizedAlgorithm</var> as <var>PartyUInfo</var>, the
+ <a href="#dfn-ConcatParams-partyVInfo">partyVInfo</a> member of
+ <var>normalizedAlgorithm</var> as <var>PartyVInfo</var>, the
+ <a href="#dfn-ConcatParams-publicInfo">publicInfo</a> member of
+ <var>normalizedAlgorithm</var>, if present and not null, as
+ <var>publicInfo</var> and the
+ <a href="#dfn-ConcatParams-privateInfo">privateInfo</a> member of
+ <var>normalizedAlgorithm</var>, if present and not null, as
+ <var>privateInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the operation fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>secret</var>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import key</dt>
+ <dd>
+ <dl class="switch">
+ <dt>
+ If <var>format</var> is <code>"raw"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains a value that is not
+ <code>"deriveKey"</code> or <code>"deriveBits"</code>,
+
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the key data provided in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"secret"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"CONCAT"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
+ of <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </dd>
+ <dt>Get length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Return null.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div id="hkdf-ctr" class="section">
+ <h3>HKDF-CTR</h3>
+ <div id="hkdf-ctr-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"HKDF-CTR"</code> algorithm identifier is used to
+ perform key derivation using the extraction-then-expansion approach described in
+ NIST SP 800-56C[<a href="#SP800-56C">SP800-56C</a>], using HMAC in counter mode,
+ as described in Section 5.1 of NIST SP 800-108
+ [<a href="#SP800-108">SP800-108</a>].
+ </p>
+ </div>
+ <div id="hkdf-ctr-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a>
+ for this algorithm is <code>"HKDF-CTR"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>deriveBits</td>
+ <td><a href="#dfn-HkdfCtrParams">HkdfCtrParams</a></td>
+ <td><a href="#dfn-ArrayBuffer">ArrayBuffer</a></td>
+ </tr>
+ <tr>
+ <td>Import key</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>Get key length</td>
+ <td>None</td>
+ <td>Integer or null</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="hkdf-ctr-params" class="section">
+ <h4>HkdfCtrParams dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-HkdfCtrParams">HkdfCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The algorithm to use with HMAC (e.g.: <a href="#sha-256">SHA-256</a>)</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-HkdfCtrParams-hash">hash</dfn>;
+<span class="comment">// A bit string that corresponds to the label that identifies the purpose for the derived keying material.</span>
+CryptoOperationData <dfn id="dfn-HkdfCtrParams-label">label</dfn>;
+<span class="comment">// A bit string that corresponds to the context of the key derivation, as described in Section 5 of NIST SP 800-108 [<a href="#SP800-108">SP800-108</a>]</span>
+CryptoOperationData <dfn id="dfn-HkdfCtrParams-context">context</dfn>;
+};
+ </x:codeblock>
+ <div class="ednote">
<p>
- The <code>"AES-CFB-8"</code> algorithm identifier is used to perform
- encryption and decryption using AES in Cipher Feedback mode, specifically CFB-8,
- as described in Section 6.3 of NIST SP 800-38A
- [<a href="#SP800-38A">SP800-38A</a>].
+ The definition of HKDF allows the caller to supply an optional pseudorandom salt
+ value, which is used as the key during the extract phase. If this value is not
+ supplied, an all zero string is used instead. However, support for an explicit
+ salt value is not widely implemented in existing APIs, nor is it required by
+ existing usages of HKDF. Should this be an optional parameter, and if so, what
+ should the behavior be of a user agent that does not support explicit salt
+ values (is it conforming or non-conforming?)
</p>
</div>
- <div id="aes-cfb-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-CFB-8"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>encrypt</td>
- <td><a href="#dfn-AesCfbParams">AesCfbParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>decrypt</td>
- <td><a href="#dfn-AesCfbParams">AesCfbParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="aes-cfb-params" class="section">
- <h4>AesCfbParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-AesCfbParams">AesCfbParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The initialization vector. <span class="RFC2119">MUST</span> be 16 bytes.</span>
- CryptoOperationData <dfn id="dfn-AesCfbParams-iv">iv</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="aes-cfb-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Encrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCfbParams">AesCfbParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-cfb-params">AesCfbParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCfbParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ciphertext</var> be the result of performing the CFB Encryption
- operation described in Section 6.3 of NIST SP 800-38A [<a
- href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
- href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-AesCfbParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter, the value 8 as the input parameter
- <var>s</var>, and <a href="#concept-contents-of-arraybuffer">the contents
- of<var>plaintext</var></a> as the input plaintext.
- </p>
- </li>
- <li>
- <p>
- Return <var>ciphertext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Decrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCfbParams">AesCfbParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-cfb-params">AesCfbParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCfbParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>plaintext</var> be the result of performing the CFB Decryption
- operation described in Section 6.3 of NIST SP 800-38A [<a
- href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a
- href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-AesCfbParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter, the the value 8 as the input parameter
- <var>s</var>, and <a href="#concept-contents-of-arraybuffer">the contents of
- <var>ciphertext</var></a> as the input ciphertext.
- </p>
- </li>
- <li>
- <p>
- Return <var>plaintext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an AES key of length
- equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CFB-8"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
-
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128CFB8"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192CFB8"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256CFB8"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
- object representing an AES key with value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CFB-8"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128CFB8"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192CFB8"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256CFB8"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> property of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> property of
- <var>normalizedDerivedKeyAlgorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="aes-kw" class="section">
- <h3>AES-KW</h3>
- <div id="aes-kw-description" class="section">
- <h4>Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"AES-KW"</code> algorithm identifier is used to perform
- key wrapping using AES, as
- described in [<a href="#rfc3394">RFC3394</a>].
- </p>
- </div>
- <div id="aes-kw-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-KW"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>wrapKey</td>
- <td>None</td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>unwrapKey</td>
- <td>None</td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="aes-kw-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Wrap Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>plaintext</var> is not a multiple of 64 bits in length,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ciphertext</var> be the result of performing the Key Wrap
- operation described in Section 2.2.1 of [<a href="#rfc3394">RFC3394</a>]
- with <var>plaintext</var> as the plaintext to be wrapped and using the default
- Initial Value defined in Section 2.2.3.1 of the same document.
- </p>
- </li>
- <li>
- <p>
- Return <var>ciphertext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Unwrap Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>plaintext</var> be the result of performing the Key Unwrap
- operation described in Section 2.2.2 of [<a href="#rfc3394">RFC3394</a>] with
- <var>ciphertext</var> as the input ciphertext and using the default Initial
- Value defined in Section 2.2.3.1 of the same document.
- </p>
- </li>
- <li>
- <p>
- If the Key Unwrap operation returns an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return <var>plaintext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> property of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- one of <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-KW"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> property of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- one of <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
-
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
-
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128KW"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192KW"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256KW"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>. </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing an AES key with value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-KW"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128KW"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192KW"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256KW"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="hmac" class="section">
- <h3>HMAC</h3>
- <div id="hmac-description" class="section">
- <h4>Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>HMAC</code> algorithm calculates and verifies hash-based message
- authentication codes according to [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>].
- </p>
- </div>
- <div id="hmac-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"HMAC"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>sign</td>
- <td>None</td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>verify</td>
- <td>None</td>
- <td>boolean</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-HmacKeyGenParams">HmacKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-HmacImportParams">HmacImportParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-HmacDerivedKeyParams">HmacDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="hmac-importparams" class="section">
- <h4>HmacImportParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-HmacImportParams">HmacImportParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The inner hash function to use.</span>
- AlgorithmIdentifier <dfn id="dfn-HmacImportParams-hash">hash</dfn>;
- <span class="comment">// The length (in bits) of the key.</span>
- [EnforceRange] unsigned long <dfn id="dfn-HmacImportParams-length">length</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="HmacKeyAlgorithm-dictionary" class="section">
- <h4>HmacKeyAlgorithm dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
- <span class="comment">// The inner hash function to use.</span>
- KeyAlgorithm <dfn id="dfn-HmacKeyAlgorithm-hash">hash</dfn>;
- <span class="comment">// The length (in bits) of the key.</span>
- unsigned long <dfn id="dfn-HmacKeyAlgorithm-length">length</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="hmac-keygen-params" class="section">
- <h4>HmacKeyGenParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-HmacKeyGenParams">HmacKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The inner hash function to use.</span>
- AlgorithmIdentifier <dfn id="dfn-HmacKeyGenParams-hash">hash</dfn>;
- <span class="comment">// The length (in bits) of the key to generate. If unspecified, the
- // recommended length will be used, which is the size of the associated hash function's block
- // size.</span>
- [EnforceRange] unsigned long <dfn id="dfn-HmacKeyGenParams-length">length</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="hmac-derivedkey-params" class="section">
- <h4>HmacDerivedKeyParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-HmacDerivedKeyParams">HmacDerivedKeyParams</dfn> : <a href="#dfn-HmacImportParams">HmacImportParams</a> {
- <span class="comment">// The length (in bits) of the key to generate. If unspecified, the
- // recommended length will be used, which is the size of the associated hash function's block
- // size.</span>
- [EnforceRange] unsigned long <dfn id="dfn-HmacDerivedKeyParams-length">length</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="hmac-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Sign</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>mac</var> be the result of performing the MAC Generation operation
- described in Section 4 of [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using
- the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
- internal slot of <var>key</var>, the hash function identified by the <a
- href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> and <var>message</var> as the input data <var>text</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>mac</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Verify</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>mac</var> be the result of performing the MAC Generation operation
- described in Section 4 of [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using
- the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
- internal slot of <var>key</var>, the hash function identified by the <a
- href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> and <var>message</var> as the input data <var>text</var>.
- </p>
- </li>
- <li>
- <p>
- Return true if <var>mac</var> is equal to <var>signature</var> and false
- otherwise.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-HmacKeyGenParams">HmacKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-HmacKeyGenParams-hash">hash</a> member is
- not present in <var>normalizedAlgorithm</var>, then
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not present:
- </dt>
- <dd>
- Let <var>length</var> be the block size in bits of the hash function
- identified by the <a href="#dfn-HmacKeyGenParams-hash">hash</a> member
- of <var>normalizedAlgorithm</var>.
- </dd>
- <dt>
- Otherwise, if the <a href="#dfn-HmacKeyGenParams-length">length</a>
- member of <var>normalizedAlgorithm</var> is non-zero:
- </dt>
- <dd>
- Let <var>length</var> be equal to the
- <a href="#dfn-HmacKeyGenParams-length">length</a>
- member of <var>normalizedAlgorithm</var>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not <code>"sign"</code> or
- <code>"verify"</code>, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate a key of length <var>length</var> bits.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"HMAC"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a new
- <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to equal the <a href="#dfn-Algorithm-name">name</a>
- member of the <a href="#dfn-HmacKeyGenParams-hash">hash</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute
- of <var>algorithm</var> to <var>hash</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var> is present and has a
- <a href="#dfn-Algorithm-name">name</a> member:
- </dt>
- <dd>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to equal the <a href="#dfn-Algorithm-name">name</a>
- member of the <a href="#dfn-HmacImportParams-hash">hash</a>
- member of <var>normalizedAlgorithm</var>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var> is present and has a
- <a href="#dfn-Algorithm-name">name</a> member:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to equal the <a
- href="#dfn-Algorithm-name">name</a> member of the <a
- href="#dfn-HmacImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is
- <code>"SHA-1"</code>:
- </dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present
- and is not <code>"HS1"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is
- <code>"SHA-256"</code>:
- </dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present
- and is not <code>"HS256"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is
- <code>"SHA-384"</code>:
- </dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present
- and is not <code>"HS384"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is
- <code>"SHA-512"</code>:
- </dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present
- and is not <code>"HS512"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the <code>alg</code> field of <var>jwk</var> is not present,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is
- <code>"HS1"</code>:
- </dt>
- <dd>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to <code>"SHA-1"</code>.
- </dd>
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is
- to <code>"HS256"</code>:
- </dt>
- <dd>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to <code>"SHA-256"</code>.
- </dd>
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is
- <code>"HS384"</code>:
- </dt>
- <dd>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to <code>"SHA-384"</code>.
- </dd>
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is
- <code>"HS512"</code>:
- </dt>
- <dd>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to <code>"SHA-512"</code>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"sign"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>length</var> be equivalent to the length, in octets, of
- <var>data</var>, multiplied by 8.
- </p>
- </li>
- <li>
- <p>
- If <var>length</var> is zero
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacImportParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is present:
- </dt>
- <dd>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacImportParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is greater than <var>length</var>:
- </dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>
- If the <a href="#dfn-HmacImportParams-length">length</a> member of
- <var>normalizedAlgorithm</var>, is less than or equal to
- <var>length</var> minus eight:
- </dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>
- Otherwise:
- </dt>
- <dd>
- Set <var>length</var> equal to the <a href="#dfn-HmacImportParams-length">
- length</a> member of <var>normalizedAlgorithm</var>.
- </dd>
- </dl>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
- object representing an HMAC key with the first <var>length</var>
- bits of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"HMAC"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-HmacKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to <var>length</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of
- <var>algorithm</var> to <var>hash</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a
- href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be the
- <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of
- <var>algorithm</var>.
- </p>
- </li>
-
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is <code>"SHA-1"</code>:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"HS1"</code>.</dd>
- <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is <code>"SHA-256"</code>:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"HS256"</code>.</dd>
- <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is <code>"SHA-384"</code>:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"HS384"</code>.</dd>
- <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is <code>"SHA-512"</code>:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"HS512"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a
- href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-HmacImportParams">HmacImportParams</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-HmacImportParams-hash">hash</a> member is
- not present in <var>normalizedDerivedKeyAlgorithm</var>, then
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not present:
- </dt>
- <dd>
- Let <var>length</var> be the block size in bytes of the hash function
- identified by the <a href="#dfn-HmacImportParams-hash">hash</a> member
- of <var>normalizedDerivedKeyAlgorithm</var>.
- </dd>
- <dt>
- Otherwise, if the <a href="#dfn-HmacDerivedKeyParams-length">length</a>
- member of <var>normalizedDerivedKeyAlgorithm</var> is non-zero:
- </dt>
- <dd>
- Let <var>length</var> be equal to the
- <a href="#dfn-HmacDerivedKeyParams-length">length</a>
- member of <var>normalizedDerivedKeyAlgorithm</var>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>length</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
- <div id="dh" class="section">
- <h3>Diffie-Hellman</h3>
- <div id="dh-description" class="section">
- <h4>Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- This describes using Diffie-Hellman for key generation and key agreement, as specified
- by <a href="#PKCS3">PKCS #3</a>.
- </p>
- </div>
- <div id="dh-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"DH"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-DhKeyGenParams">DhKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>deriveBits</td>
- <td><a href="#dfn-DhKeyDeriveParams">DhKeyDeriveParams</a></td>
- <td>Octet string</td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-DhImportKeyParams">DhImportKeyParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="dh-DhKeyGenParams" class="section">
- <h4>DhKeyGenParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-DhKeyGenParams">DhKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The prime p.</span>
- BigInteger <dfn id="dfn-DhKeyGenParams-prime">prime</dfn>;
- <span class="comment">// The base g.</span>
- BigInteger <dfn id="dfn-DhKeyGenParams-generator">generator</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="dh-DhKeyAlgorithm" class="section">
- <h4>DhKeyAlgorithm dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-DhKeyAlgorithm">DhKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
- <span class="comment">// The prime p.</span>
- BigInteger <dfn id="dfn-DhKeyAlgorithm-prime">prime</dfn>;
- <span class="comment">// The base g.</span>
- BigInteger <dfn id="dfn-DhKeyAlgorithm-generator">generator</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="dh-DhKeyDeriveParams" class="section">
- <h4>DhKeyDeriveParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-DhKeyDeriveParams">DhKeyDeriveParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The peer's public value.</span>
- <a href="#dfn-CryptoKey">CryptoKey</a> <dfn id="dfn-DhKeyDeriveParams-public">public</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="dh-DhImportKeyParams" class="section">
- <h4>DhImportKeyParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-DhImportKeyParams">DhImportKeyParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The prime p.</span>
- BigInteger <dfn id="dfn-DhImportKeyParams-prime">prime</dfn>;
- <span class="comment">// The base g.</span>
- BigInteger <dfn id="dfn-DhImportKeyParams-generator">generator</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="dh-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-DhKeyGenParams">DhKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-DhKeyGenParams">DhKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains a value which is not
- one of <code>"deriveKey"</code> or <code>"deriveBits"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate a Diffie-Hellman key pair, as defined in Section 7 of
- [<a href="#PKCS3">PKCS #3</a>], with prime, <var>p</var>, and base,
- <var>g</var>, as specified in the
- <a href="#dfn-DhKeyGenParams-prime">prime</a> and
- <a href="#dfn-DhKeyGenParams-generator">generator</a> properties of
- <var>normalizedAlgorithm</var>, respectively.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-Algorithm-name">name</a> member of
- <var>algorithm</var> to <code>"DH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-DhKeyGenParams-prime">prime</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-DhKeyGenParams-generator">generator</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the empty list.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to be <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to be <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object, as
- defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- <dt>Derive Bits</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-DhKeyDeriveParams">DhKeyDeriveParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a
- href="#dfn-DhKeyDeriveParams">DhKeyDeriveParams</a> are not present in
- <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be the
- <a href="#dfn-DhKeyDeriveParams-public">public</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> is not <code>"DH"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> is not equal to the <a
- href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
- named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of the
- [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> is not equal to the <a
- href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
- named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the Diffie-Hellman Phase II algorithm as specified in Section 8 of [<a
- href="#PKCS3">PKCS #3</a>] with <var>key</var> as the DH private value
- <var>x</var> and the Diffie-Hellman public value represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of the <a
- href="#dfn-DhKeyDeriveParams-public">public</a> member of
- <var>normalizedAlgorithm</var> as the other's public value <var>PV'</var>.
- </p>
- <dl class="switch">
- <dt>If performing the operation results in an error:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- Let <var>secret</var> be the output of the DH Phase II, <var>SK</var>.
- </dd>
- </dl>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the length of <var>secret</var> in bits is less than
- <var>length</var>:
- </dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>Return the first <var>length</var> bits of <var>secret</var>.</dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <dl class="switch">
- <dt>
- If <var>format</var> is <code>"raw"</code>:
- </dt>
- <dd>
- <div class="ednote">
- <p>
- Raw import of private values is presently not supported.
- </p>
- </div>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-DhImportKeyParams">DhImportKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a
- href="#dfn-DhImportKeyParams">DhImportKeyParams</a> are not present in
- <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>extractable</var> is false,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>PV</var> be the integer which results from interpreting the
- octets of <var>keyData</var> as an unsigned big integer with most
- significant octet first.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing a Diffie-Hellman public key with public value <var>PV</var>
- and with prime, <var>p</var> and base, <var>g</var> equal to the <a
- href="#dfn-DhImportKeyParams-prime">prime</a> and <a
- href="#dfn-DhImportKeyParams-generator">generator</a> properties of
- <var>normalizedAlgorithm</var> respectively.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"public"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a
- href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-Algorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"DH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
- <var>algorithm</var> to equal the <a
- href="#dfn-DhImportKeyParams-prime">prime</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
- <var>algorithm</var> to equal the <a
- href="#dfn-DhImportKeyParams-generator">generator</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
- of <var>key</var> to <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>
- If <var>format</var> is <code>"spki"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the <a
- href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a> algorithm
- over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is not
- equivalent to the <code>dhKeyAgreement</code> OID defined in Section 9 of
- [<a href="#PKCS3">PKCS #3</a>], then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the <code>algorithm</code>
- AlgorithmIdentifier field of <var>spki</var> is absent, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not an instance of the <code>DHParameter</code>
- ASN.1 type defined in Section 9 of <a href="#PKCS3">PKCS #3</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the Diffie-Hellman public key obtained by parsing the
- <code>subjectPublicKey</code> field of <var>spki</var> as an ASN.1
- INTEGER.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"public"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a
- href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-Algorithm-name">name</a> member of
- <var>algorithm</var> to <code>"DH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
- <var>algorithm</var> to a new <code>BigInteger</code> equal to the
- octet string encoding of the <code>prime</code> field of
- <var>params</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
- <var>algorithm</var> to a new <code>BigInteger</code> equal to the
- octet string encoding of the <code>base</code> field of
- <var>params</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
- of <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>
- If <var>format</var> is <code>"pkcs8"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains a value which is not one of
- <code>"deriveKey"</code> or <code>"deriveBits"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>algorithm</code> AlgorithmIdentifier field of
- <var>privateKeyInfo</var> is not equivalent to the
- <code>dhKeyAgreement</code> OID defined in Section 9 of [<a
- href="#PKCS3">PKCS #3</a>], then <a href="#concept-return-an-error">return
- an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field of
- <var>privateKeyInfo</var> is absent, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field of
- <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not an instance of the <code>DHParameter</code>
- ASN.1 type defined in Section 9 of <a href="#PKCS3">PKCS #3</a>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
+ </div>
+ <div id="hkdf2-ctr-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Derive Bits</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>length</var> is null, then <a href="#concept-return-an-error">return
+ an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var> does not describe a <a href="#algorithms">
+ recognized algorithm</a> that supports the digest operation, then
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>extractKey</var> be a key equal to <var>n</var> zero bits where
+ <var>n</var> is the size of the output of the hash function described by the
+ <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>prf</var> be the MAC Generation function described in Section 4 of
+ [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using the hash function
+ described by the <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>keyDerivationKey</var> be the result of performing <var>prf</var>
+ using <var>extractKey</var> as the key and the secret represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ as the message.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of performing the KDF in counter
+ mode operation described in Section 5.1 of NIST SP 800-108
+ [<a href="#SP800-108">SP800-108</a>] using:
+ </p>
+ <ul>
+ <li>
+ <p>
+ <var>prf</var> as the Pseudo-Random Function, <var>PRF</var>,
+ </p>
+ </li>
+ <li>
+ <p>
+ <var>keyDerivationKey</var> as the Key derivation key,
+ <var>K<sub>I</sub></var>,
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-HkdfCtrParams-label">label</a> member of
+ <var>normalizedAlgorithm</var> as <var>Label</var>,
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a
+ href="#dfn-HkdfCtrParams-label">context</a> member of
+ <var>normalizedAlgorithm</var> as <var>Context</var>,
+ </p>
+ </li>
+ <li>
+ <p>
+ <var>length</var> as the value of <var>L</var>,
+ </p>
+ </li>
+ <li>
+ <p>
+ 32 as the value of <var>r</var>, and
+ </p>
+ </li>
+ <li>
+ <p>
+ the 32-bit little-endian binary encoding of <var>length</var>
+ as the encoded length value [<var>L</var>]<sub>2</sub>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ If the key derivation operation fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import key</dt>
+ <dd>
+ <dl class="switch">
+ <dt>
+ If <var>format</var> is <code>"raw"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains a value that is not
+ <code>"deriveKey"</code> or <code>"deriveBits"</code>,
+
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the Diffie-Hellman private key obtained by parsing the
- <code>privateKey</code> field of <var>privateKeyInfo</var> as an ASN.1
- INTEGER.
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"private"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-Algorithm-name">name</a> member of
- <var>algorithm</var> to <code>"DH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
- <var>algorithm</var> to a new <code>BigInteger</code> equal to the
- octet string encoding of the <code>prime</code> field of
- <var>params</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
- <var>algorithm</var> to a new <code>BigInteger</code> equal to the
- octet string encoding of the <code>base</code> field of
- <var>params</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
- of <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>format</var> is <code>"raw"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>"public"</code>:
- </dt>
- <dd>
- Let <var>data</var> be the Public Value, <var>PV</var>, associated
- with <var>key</var> as specified in Section 7 of [<a
- href="#PKCS3">PKCS #3</a>].
- </dd>
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>"private"</code>:
- </dt>
- <dd>
- Let <var>data</var> be the octet string that represents the private
- value <var>x</var> associated with <var>key</var> as a big integer,
- most significant octet first.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>
- If <var>format</var> is <code>"spki"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a
- href="#concept-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithmIdentifier</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 structure with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the
- <code>dhKeyAgreement</code> OID defined in Section 9 of <a
- href="#PKCS3">PKCS #3</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>DHParams</code> ASN.1 structure defined in Section 9 of
- <a href="#PKCS3">PKCS #3</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>prime</var> field to an ASN.1 INTEGER that is
- equivalent to the <a
- href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>base</var> field to an ASN.1 INTEGER that is
- equivalent to the <a
- href="#dfn-DhKeyAlgorithm-generator">generator</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> to an ASN.1 INTEGER that
- corresponds to the Diffie-Hellman public value represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>
- If <var>format</var> is <code>"pkcs8"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"private"</code>, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a
- href="#concept-encode-a-privateKeyInfo">encoding a
- privateKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to a
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 structure with
- the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the
- <code>dhKeyAgreement</code> OID defined in Section 9 of <a
- href="#PKCS3">PKCS #3</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>DHParams</code> ASN.1 structure defined in Section 9 of
- <a href="#PKCS3">PKCS #3</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>prime</var> field to an ASN.1 INTEGER that is
- equivalent to the <a
- href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
- the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>base</var> field to an ASN.1 INTEGER that is
- equivalent to the <a
- href="#dfn-DhKeyAlgorithm-generator">generator</a>
- attribute of the [[<a
- href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to an ASN.1 INTEGER that
- corresponds to the Diffie-Hellman private value represented by
- [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
- <div id="sha" class="section">
- <h3>SHA</h3>
- <div id="sha-description" class="section">
- <h4>Description</h4>
- <p>
- This describes the SHA-1 and SHA-2 families, as specified by
- [<a href="#FIPS180-4">FIPS PUB 180-4</a>].
- </p>
- </div>
- <div id="sha-registration" class="section">
- <h4>Registration</h4>
- <p>
- The following algorithms are added as <a href="#recognized-algorithm-name">
- recognized algorithm names</a>:
- </p>
- <dl>
- <dt id="alg-sha-1"><code>"SHA-1"</code></dt>
- <dd>The SHA-1 algorithm as specified in Section 6.1</dd>
- <dt id="alg-sha-256"><code>"SHA-256"</code></dt>
- <dd>The SHA-256 algorithm as specified in Section 6.2</dd>
- <dt id="alg-sha-384"><code>"SHA-384"</code></dt>
- <dd>The SHA-384 algorithm as specified in Section 6.5</dd>
- <dt id="alg-sha-512"><code>"SHA-512"</code></dt>
- <dd>The SHA-512 algorithm as specified in Section 6.4</dd>
- </dl>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>digest</td>
- <td>None</td>
- <td>ArrayBuffer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="sha-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Digest</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> is a cases-sensitive string match for
- <code>"SHA-1"</code>:
- </dt>
- <dd>
- Let <var>result</var> be the result of performing the SHA-1 hash function
- defined in Section 6.1 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
- <var>message</var> as the input message, <var>M</var>.
- </dd>
- <dt>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> is a cases-sensitive string match for
- <code>"SHA-256"</code>:
- </dt>
- <dd>
- Let <var>result</var> be the result of performing the SHA-256 hash function
- defined in Section 6.2 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
- <var>message</var> as the input message, <var>M</var>.
- </dd>
- <dt>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> is a cases-sensitive string match for
- <code>"SHA-384"</code>:
- </dt>
- <dd>
- Let <var>result</var> be the result of performing the SHA-384 hash function
- defined in Section 6.5 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
- <var>message</var> as the input message, <var>M</var>.
- </dd>
- <dt>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> is a cases-sensitive string match for
- <code>"SHA-512"</code>:
- </dt>
- <dd>
- Let <var>result</var> be the result of performing the SHA-1 hash function
- defined in Section 6.4 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
- <var>message</var> as the input message, <var>M</var>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If performing the operation results in an error, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return a new ArrayBuffer containing <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
- <div id="concatkdf" class="section">
- <h3>Concat KDF</h3>
- <div id="concatkdf-description" class="section">
- <h4>Description</h4>
- <p>
- The <code>"CONCAT"</code> algorithm identifier is used to perform key derivation
- using the key derivation algorithm defined in Section 5.8.1 of NIST SP 800-56A
- [<a href="#SP800-56A">SP800-56A</a>].
- </p>
- </div>
- <div id="concatkdf-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"CONCAT"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>deriveBits</td>
- <td><a href="#dfn-ConcatParams">ConcatParams</a></td>
- <td>Octet string</td>
- </tr>
- <tr>
- <td>Import key</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>Get key length</td>
- <td>None</td>
- <td>Integer or null</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="concat-params" class="section">
- <h4>ConcatParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-ConcatParams">ConcatParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The digest method to use to derive the keying material.</span>
- AlgorithmIdentifier <dfn id="dfn-ConcatParams-hash">hash</dfn>;
-
- <span class="comment">// A bit string corresponding to the AlgorithmId field of the OtherInfo parameter.</span>
- <span class="comment">// The AlgorithmId indicates how the derived keying material will be parsed and for which</span>
- <span class="comment">// algorithm(s) the derived secret keying material will be used.</span>
- CryptoOperationData <dfn id="dfn-ConcatParams-algorithmId">algorithmId</dfn>;
- <span class="comment">// A bit string that corresponds to the PartyUInfo field of the OtherInfo parameter.</span>
- CryptoOperationData <dfn id="dfn-ConcatParams-partyUInfo">partyUInfo</dfn>;
- <span class="comment">// A bit string that corresponds to the PartyVInfo field of the OtherInfo parameter.</span>
- CryptoOperationData <dfn id="dfn-ConcatParams-partyVInfo">partyVInfo</dfn>;
- <span class="comment">// An optional bit string that corresponds to the SuppPubInfo field of the OtherInfo parameter.</span>
- CryptoOperationData? <dfn id="dfn-ConcatParams-publicInfo">publicInfo</dfn>;
- <span class="comment">// An optional bit string that corresponds to the SuppPrivInfo field of the OtherInfo parameter.</span>
- CryptoOperationData? <dfn id="dfn-ConcatParams-privateInfo">privateInfo</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="concat-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Derive Bits</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-ConcatParams">ConcatParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the
- <a href="#dfn-ConcatParams-hash">hash</a>,
- <a href="#dfn-ConcatParams-algorithmId">algorithmId</a>,
- <a href="#dfn-ConcatParams-partyUInfo">partyUInfo</a> or
- <a href="#dfn-ConcatParams-partyVInfo">partyVInfo</a> properties are not
- present in <var>normalizedAlgorithm</var>, then
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>secret</var> be the result of performing the Concatenation Key
- Derivation Function defined in Section 5.8.1 of
- [<a href="#SP800-56A">SP800-56A</a>] with <var>length</var> as
- <var>keydatalen</var>, the hash function identified by the
- <a href="#dfn-ConcatParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var> as <var>H</var>, the
- <a href="#dfn-ConcatParams-algorithmId">algorithmId</a> member of
- <var>normalizedAlgorithm</var> as <var>AlgorithmID</var>, the
- <a href="#dfn-ConcatParams-partyUInfo">partyUInfo</a> member of
- <var>normalizedAlgorithm</var> as <var>PartyUInfo</var>, the
- <a href="#dfn-ConcatParams-partyVInfo">partyVInfo</a> member of
- <var>normalizedAlgorithm</var> as <var>PartyVInfo</var>, the
- <a href="#dfn-ConcatParams-publicInfo">publicInfo</a> member of
- <var>normalizedAlgorithm</var>, if present and not null, as
- <var>publicInfo</var> and the
- <a href="#dfn-ConcatParams-privateInfo">privateInfo</a> member of
- <var>normalizedAlgorithm</var>, if present and not null, as
- <var>privateInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If the operation fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return <var>secret</var>
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import key</dt>
- <dd>
- <dl class="switch">
- <dt>
- If <var>format</var> is <code>"raw"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains a value that is not
- <code>"deriveKey"</code> or <code>"deriveBits"</code>,
-
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the key data provided in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"secret"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"CONCAT"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
- of <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </dd>
- <dt>Get length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Return null.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
- <div id="hkdf-ctr" class="section">
- <h3>HKDF-CTR</h3>
- <div id="hkdf-ctr-description" class="section">
- <h4>Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"HKDF-CTR"</code> algorithm identifier is used to
- perform key derivation using the extraction-then-expansion approach described in
- NIST SP 800-56C[<a href="#SP800-56C">SP800-56C</a>], using HMAC in counter mode,
- as described in Section 5.1 of NIST SP 800-108
- [<a href="#SP800-108">SP800-108</a>].
- </p>
- </div>
- <div id="hkdf-ctr-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a>
- for this algorithm is <code>"HKDF-CTR"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>deriveBits</td>
- <td><a href="#dfn-HkdfCtrParams">HkdfCtrParams</a></td>
- <td><a href="#dfn-ArrayBuffer">ArrayBuffer</a></td>
- </tr>
- <tr>
- <td>Import key</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>Get key length</td>
- <td>None</td>
- <td>Integer or null</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="hkdf-ctr-params" class="section">
- <h4>HkdfCtrParams dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-HkdfCtrParams">HkdfCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The algorithm to use with HMAC (e.g.: <a href="#sha-256">SHA-256</a>)</span>
- AlgorithmIdentifier <dfn id="dfn-HkdfCtrParams-hash">hash</dfn>;
- <span class="comment">// A bit string that corresponds to the label that identifies the purpose for the derived keying material.</span>
- CryptoOperationData <dfn id="dfn-HkdfCtrParams-label">label</dfn>;
- <span class="comment">// A bit string that corresponds to the context of the key derivation, as described in Section 5 of NIST SP 800-108 [<a href="#SP800-108">SP800-108</a>]</span>
- CryptoOperationData <dfn id="dfn-HkdfCtrParams-context">context</dfn>;
-};
- </x:codeblock>
- <div class="ednote">
- <p>
- The definition of HKDF allows the caller to supply an optional pseudorandom salt
- value, which is used as the key during the extract phase. If this value is not
- supplied, an all zero string is used instead. However, support for an explicit
- salt value is not widely implemented in existing APIs, nor is it required by
- existing usages of HKDF. Should this be an optional parameter, and if so, what
- should the behavior be of a user agent that does not support explicit salt
- values (is it conforming or non-conforming?)
- </p>
- </div>
- </div>
- <div id="hkdf2-ctr-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Derive Bits</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>length</var> is null,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-HkdfCtrParams">HkdfCtrParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-HkdfCtrParams">HkdfCtrParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var> does not describe a <a href="#algorithms">
- recognized algorithm</a> that supports the digest operation, then
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
- </p>
- </li>
- <li>
- <p>
- Let <var>extractKey</var> be a key equal to <var>n</var> zero bits where
- <var>n</var> is the size of the output of the hash function described by the
- <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>prf</var> be the MAC Generation function described in Section 4 of
- [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using the hash function
- described by the <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>keyDerivationKey</var> be the result of performing <var>prf</var>
- using <var>extractKey</var> as the key and the secret represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- as the message.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of performing the KDF in counter
- mode operation described in Section 5.1 of NIST SP 800-108
- [<a href="#SP800-108">SP800-108</a>] using:
- </p>
- <ul>
- <li>
- <p>
- <var>prf</var> as the Pseudo-Random Function, <var>PRF</var>,
- </p>
- </li>
- <li>
- <p>
- <var>keyDerivationKey</var> as the Key derivation key,
- <var>K<sub>I</sub></var>,
- </p>
- </li>
- <li>
- <p>
- <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-HkdfCtrParams-label">label</a> member of
- <var>normalizedAlgorithm</var> as <var>Label</var>,
- </p>
- </li>
- <li>
- <p>
- <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a
- href="#dfn-HkdfCtrParams-label">context</a> member of
- <var>normalizedAlgorithm</var> as <var>Context</var>,
- </p>
- </li>
- <li>
- <p>
- <var>length</var> as the value of <var>L</var>,
- </p>
- </li>
- <li>
- <p>
- 32 as the value of <var>r</var>, and
- </p>
- </li>
- <li>
- <p>
- the 32-bit little-endian binary encoding of <var>length</var>
- as the encoded length value [<var>L</var>]<sub>2</sub>.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- If the key derivation operation fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import key</dt>
- <dd>
- <dl class="switch">
- <dt>
- If <var>format</var> is <code>"raw"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains a value that is not
- <code>"deriveKey"</code> or <code>"deriveBits"</code>,
-
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the key data provided in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"secret"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"HKDF-CTR"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
- of <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </dd>
- <dt>Get length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Return null.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="pbkdf2" class="section">
- <h3>PBKDF2</h3>
- <div id="pbkdf2-description" class="section">
- <h4>Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"PBKDF2"</code> algorithm identifier is used to
- perform key derivation using the PKCS#5 password-based key
- derivation function version 2.0, as defined in
- [<a href="#rfc2898">RFC2898</a>] using HMAC as the pseudo-random function.
- </p>
- </div>
- <div id="pbkdf2-registration" class="section">
- <h4>Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"PBKDF2"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>generateKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>deriveBits</td>
- <td><a href="#dfn-Pbkdf2Params">Pbkdf2Params</a></td>
- <td><a href="#dfn-ArrayBuffer">ArrayBuffer</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>Get key length</td>
- <td>None</td>
- <td>Length or null</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="pbkdf2-params" class="section">
- <h4>Pbkdf2Params dictionary</h4>
- <x:codeblock language="idl">
-dictionary <dfn id="dfn-Pbkdf2Params">Pbkdf2Params</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- CryptoOperationData <dfn id="dfn-Pbkdf2Params-salt">salt</dfn>;
- [EnforceRange] unsigned long <dfn id="dfn-Pbkdf2Params-iterations">iterations</dfn>;
- AlgorithmIdentifier <dfn id="dfn-Pbkdf2Params-hash">hash</dfn>;
-};
- </x:codeblock>
- </div>
- <div id="pbkdf2-operations" class="section">
- <h4>Operations</h4>
- <dl>
- <dt>Derive bits</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Pbkdf2Params">Pbkdf2Params</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-Pbkdf2Params">Pbkdf2Params</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>length</var> is null or is not a multiple of 8, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Pbkdf2Params-hash">hash</a> member of
- <var>normalizedAlgorithm</var> does not describe a <a href="#algorithms">
- recognized algorithm</a> that supports the digest operation, then
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
- </p>
- </li>
- <li>
- <p>
- Let <var>prf</var> be the MAC Generation function described in Section 4 of
- [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using the hash function
- described by the <a href="#dfn-Pbkdf2Params-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of performing the PBKDF2 operation defined
- in Section 5.2 of [<a href="#rfc2898">RFC2898</a>] using <var>prf</var> as the
- pseudo-random function, <var>PRF</var>, the password represented by [[<a
- href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- as the password, <var>P</var>, <a href="#concept-contents-of-arraybuffer">the
- contents of</a> the <a href="#dfn-Pbkdf2Params-salt">salt</a> attribute of
- <var>normalizedAlgorithm</var> as the salt, <var>S</var>, the value of the <a
- href="#dfn-Pbkdf2Params-iterations">iterations</a> attribute of
- <var>normalizedAlgorithm</var> as the iteration count, <var>c</var>, and
- <var>length</var> divided by 8 as the intended key length, <var>dkLen</var>.
- </p>
- </li>
- <li>
- <p>
- If the key derivation operation fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return <var>result</var>
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains any element that is not
- <code>"deriveKey"</code>, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>extractable</var> is true, then <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate a new password by prompting the user.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the provided password as a series of bytes encoded using UTF-8.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"secret"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"PBKDF2"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>format</var> is not <code>"raw"</code>, <a
- href="#concept-return-an-error">return an error</a> named <a
- href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any element that is not
- <code>"deriveKey"</code>, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"secret"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"PBKDF2"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Return null.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
+ representing the key data provided in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"secret"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"HKDF-CTR"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
+ of <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </dd>
+ <dt>Get length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Return null.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
</div>
</div>
-
- <div id="algorithm-normalizing-rules" class="section">
- <h2>Algorithm normalizing rules</h2>
- <p>
- The <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> typedef permits algorithms
- to be specified as either an <a href="#dfn-Algorithm">Algorithm</a> dictionary or a <a
- href="#dfn-DOMString">DOMString</a>. The <a href="#dfn-DOMString">DOMString</a> option
- permits algorithms to be specified using shorthand 'aliases'. Algorithms may define
- aliases and the values they correspond to. Using an alias is exactly equivalent to using
- the value corresponding to the alias.
- </p>
- <p>
- Additionally, many algorithms define a subclass of the
- <a href="#dfn-Algorithm">Algorithm</a> type. As a result Web IDL type mapping to the
- correct subclass must be performed at the appropriate time.
- </p>
- <p>
- When this specification says that a value <var>algorithm</var> be <dfn
- id="concept-normalize-to-type">normalized to <var>type</var></dfn> the user agent must
- perform the following steps:
- </p>
- <ol>
- <li>
- <p>
- Let <var>mappedAlgorithm</var> be the result of mapping <var>algorithm</var> to
- the <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> type as specified in
- [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>mappedAlgorithm</var> is a DOMString, then:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>mappedAlgorithm</var> contains any non-ASCII characters,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Convert every character in <var>mappedAlgorithm</var> to lower case.
- </p>
- </li>
- <li>
- <p>
- If <var>mappedAlgorithm</var> is equal to a recognized
- <a href="#dfn-algorithm-alias">algorithm alias</a> then let
- <var>objectAlgorithm</var> be the value defined to be equivalent
- to this alias.
- </p>
- </li>
- <li>
- <p>
- Otherwise, <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>Let <var>objectAlgorithm</var> equal <var>algorithm</var>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of mapping <var>objectAlgorithm</var> to
- <var>type</var> as specified in [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- <li>
- <p>
- If a member, <var>memberName</var>, of <var>type</var> has a type that is a union of
- <a href="#dfn-DOMString">DOMString</a> and a type, <var>memberType</var>, that is
- either <a href="#dfn-Algorithm">Algorithm</a> or a subclass of <a
- href="#dfn-Algorithm">Algorithm</a> and if the <var>memberName</var> member of
- <var>result</var> is present and has type <a href="#dfn-DOMString">DOMString</a>, then
- replace <var>memberName</var> in <var>result</var> with the result of <a
- href="#dfn-normalize-to-type">normalizing</a> the <var>memberName</var> member of
- <var>result</var> to <var>memberType</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
+
+ <div id="pbkdf2" class="section">
+ <h3>PBKDF2</h3>
+ <div id="pbkdf2-description" class="section">
+ <h4>Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"PBKDF2"</code> algorithm identifier is used to
+ perform key derivation using the PKCS#5 password-based key
+ derivation function version 2.0, as defined in
+ [<a href="#rfc2898">RFC2898</a>] using HMAC as the pseudo-random function.
+ </p>
+ </div>
+ <div id="pbkdf2-registration" class="section">
+ <h4>Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"PBKDF2"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>generateKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>deriveBits</td>
+ <td><a href="#dfn-Pbkdf2Params">Pbkdf2Params</a></td>
+ <td><a href="#dfn-ArrayBuffer">ArrayBuffer</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>Get key length</td>
+ <td>None</td>
+ <td>Length or null</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="pbkdf2-params" class="section">
+ <h4>Pbkdf2Params dictionary</h4>
+ <x:codeblock language="idl">
+dictionary <dfn id="dfn-Pbkdf2Params">Pbkdf2Params</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+CryptoOperationData <dfn id="dfn-Pbkdf2Params-salt">salt</dfn>;
+[EnforceRange] unsigned long <dfn id="dfn-Pbkdf2Params-iterations">iterations</dfn>;
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-Pbkdf2Params-hash">hash</dfn>;
+};
+ </x:codeblock>
+ </div>
+ <div id="pbkdf2-operations" class="section">
+ <h4>Operations</h4>
+ <dl>
+ <dt>Derive bits</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>length</var> is null or is not a multiple of 8, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-Pbkdf2Params-hash">hash</a> member of
+ <var>normalizedAlgorithm</var> does not describe a <a href="#algorithms">
+ recognized algorithm</a> that supports the digest operation, then
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>prf</var> be the MAC Generation function described in Section 4 of
+ [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using the hash function
+ described by the <a href="#dfn-Pbkdf2Params-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of performing the PBKDF2 operation defined
+ in Section 5.2 of [<a href="#rfc2898">RFC2898</a>] using <var>prf</var> as the
+ pseudo-random function, <var>PRF</var>, the password represented by [[<a
+ href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ as the password, <var>P</var>, <a href="#concept-contents-of-arraybuffer">the
+ contents of</a> the <a href="#dfn-Pbkdf2Params-salt">salt</a> attribute of
+ <var>normalizedAlgorithm</var> as the salt, <var>S</var>, the value of the <a
+ href="#dfn-Pbkdf2Params-iterations">iterations</a> attribute of
+ <var>normalizedAlgorithm</var> as the iteration count, <var>c</var>, and
+ <var>length</var> divided by 8 as the intended key length, <var>dkLen</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key derivation operation fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains any element that is not
+ <code>"deriveKey"</code>, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>extractable</var> is true, then <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate a new password by prompting the user.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the provided password as a series of bytes encoded using UTF-8.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"secret"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"PBKDF2"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>format</var> is not <code>"raw"</code>, <a
+ href="#concept-return-an-error">return an error</a> named <a
+ href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any element that is not
+ <code>"deriveKey"</code>, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"secret"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"PBKDF2"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Return null.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
</div>
+
+
<div id="examples-section" class="section">
<h2>JavaScript Example Code</h2>
<div id="examples-signing" class="section">
--- a/spec/Overview.html Mon Jun 16 00:00:00 2014 -0700
+++ b/spec/Overview.html Mon Jun 16 00:00:00 2014 -0700
@@ -134,7 +134,7 @@
<div id="toc">
<h2>Table of Contents</h2>
- <div class="toc"><ul><li><a href="#introduction">1. Introduction</a></li><li><a href="#use-cases">2. Use Cases</a><ul><li><a href="#multifactor-authentication">2.1. Multi-factor Authentication</a></li><li><a href="#protected-document">2.2. Protected Document Exchange</a></li><li><a href="#cloud-storage">2.3. Cloud Storage</a></li><li><a href="#document-signing">2.4. Document Signing</a></li><li><a href="#data-integrity-protection">2.5. Data Integrity Protection</a></li><li><a href="#secure-messaging">2.6. Secure Messaging</a></li><li><a href="#jose">2.7. Javascript Object Signing and Encryption (JOSE)</a></li></ul></li><li><a href="#conformance">3. Conformance</a></li><li><a href="#scope">4. Scope</a><ul><li><a href="#scope-abstraction">4.1. Level of abstraction</a></li><li><a href="#scope-algorithms">4.2. Cryptographic algorithms</a></li><li><a href="#scope-operations">4.3. Operations</a></li><li><a href="#scope-out-of-scope">4.4. Out of scope</a></li></ul></li><li><a href="#concepts">5. Concepts</a><ul><li><a href="#concepts-underlying-implementation">5.1. Underlying Cryptographic Implementation</a></li><li><a href="#concepts-key-storage">5.2. Key Storage</a></li></ul></li><li><a href="#security">6. Security considerations</a><ul><li><a href="#security-implementers">6.1. Security considerations for implementers</a></li><li><a href="#security-developers">6.2. Security considerations for authors</a></li><li><a href="#security-users">6.3. Security considerations for users</a></li></ul></li><li><a href="#privacy">7. Privacy considerations</a></li><li><a href="#dependencies">8. Dependencies</a></li><li><a href="#terminology">9. Terminology</a></li><li><a href="#RandomSource-interface">10. RandomSource interface</a><ul><li><a href="#RandomSource-description">10.1. Description</a></li><li><a href="#RandomSource-interface-methods">10.2. Methods and Parameters</a><ul><li><a href="#RandomSource-method-getRandomValues">10.2.1. The getRandomValues method</a></li></ul></li></ul></li><li><a href="#algorithm-dictionary">11. Algorithm dictionary</a><ul><li><a href="#algorithm-dictionary-members">11.1. Algorithm Dictionary Members</a></li></ul></li><li><a href="#key-algorithm-dictionary">12. KeyAlgorithm dictionary</a><ul><li><a href="#key-algorithm-dictionary-description">12.1. Description</a></li><li><a href="#key-algorithm-dictionary-members">12.2. KeyAlgorithm dictionary members</a></li></ul></li><li><a href="#cryptokey-interface">13. CryptoKey interface</a><ul><li><a href="#cryptokey-interface-description">13.1. Description</a></li><li><a href="#cryptokey-interface-types">13.2. Key interface data types</a></li><li><a href="#cryptokey-interface-internal-slots">13.3. CryptoKey internal slots</a></li><li><a href="#cryptokey-interface-members">13.4. CryptoKey interface members</a></li><li><a href="#cryptokey-interface-clone">13.5. Structured clone algorithm</a></li></ul></li><li><a href="#crypto-interface">14. Crypto interface</a></li><li><a href="#subtlecrypto-interface">15. SubtleCrypto interface</a><ul><li><a href="#subtlecrypto-interface-description">15.1. Description</a></li><li><a href="#subtlecrypto-interface-datatypes">15.2. Data Types</a></li><li><a href="#subtlecrypto-interface-methods">15.3. Methods and Parameters</a><ul><li><a href="#SubtleCrypto-method-encrypt">15.3.1. The encrypt method</a></li><li><a href="#SubtleCrypto-method-decrypt">15.3.2. The decrypt method</a></li><li><a href="#SubtleCrypto-method-sign">15.3.3. The sign method</a></li><li><a href="#SubtleCrypto-method-verify">15.3.4. The verify method</a></li><li><a href="#SubtleCrypto-method-digest">15.3.5. The digest method</a></li><li><a href="#SubtleCrypto-method-generateKey">15.3.6. The generateKey method</a></li><li><a href="#SubtleCrypto-method-deriveKey">15.3.7. The deriveKey method</a></li><li><a href="#SubtleCrypto-method-deriveBits">15.3.8. The deriveBits method</a></li><li><a href="#SubtleCrypto-method-importKey">15.3.9. The importKey method</a></li><li><a href="#SubtleCrypto-method-exportKey">15.3.10. The exportKey method</a></li><li><a href="#SubtleCrypto-method-wrapKey">15.3.11. The wrapKey method</a></li><li><a href="#SubtleCrypto-method-unwrapKey">15.3.12. The unwrapKey method</a></li></ul></li><li><a href="#SubtleCrypto-Exceptions">15.4. Exceptions</a></li></ul></li><li><a href="#JsonWebKey-dictionary">16. JsonWebKey dictionary</a></li><li><a href="#WorkerCrypto-interface">17. WorkerCrypto interface</a><ul><li><a href="#WorkerCrypto-description">17.1. Description</a></li></ul></li><li><a href="#big-integer">18. BigInteger</a></li><li><a href="#keypair">19. CryptoKeyPair dictionary</a></li><li><a href="#algorithms">20. Algorithms</a><ul><li><a href="#algorithms-index">20.1. Registered algorithms</a></li><li><a href="#recommended-algorithms">20.2. Recommended algorithms</a></li><li><a href="#defining-an-algorithm">20.3. Defining an algorithm</a><ul><li><a href="#recognized-algorithm-name">20.3.1. Recognized algorithm name</a></li><li><a href="#supported-operations">20.3.2. Supported operations</a></li><li><a href="#algorithm-specific-params">20.3.3. Algorithm-specific parameters</a></li><li><a href="#algorithm-result">20.3.4. Algorithm results</a></li><li><a href="#algorithm-alias">20.3.5. Algorithm aliases</a></li></ul></li><li><a href="#rsassa-pkcs1">20.4. RSASSA-PKCS1-v1_5</a><ul><li><a href="#rsassa-pkcs1-description">20.4.1. Description</a></li><li><a href="#rsassa-pkcs1-registration">20.4.2. Registration</a></li><li><a href="#RsaHashedKeyGenParams-dictionary">20.4.3. RsaHashedKeyGenParams dictionary</a></li><li><a href="#RsaHashedKeyAlgorithm-dictionary">20.4.4. RsaHashedKeyAlgorithm dictionary</a></li><li><a href="#RsaHashedImportParams-dictionary">20.4.5. RsaHashedImportParams dictionary</a></li><li><a href="#rsassa-pkcs1-operations">20.4.6. Operations</a></li></ul></li><li><a href="#rsa-pss">20.5. RSA-PSS</a><ul><li><a href="#rsa-pss-description">20.5.1. Description</a></li><li><a href="#rsa-pss-registration">20.5.2. Registration</a></li><li><a href="#RsaPssParams-dictionary">20.5.3. RsaPssParams dictionary</a></li><li><a href="#rsa-pss-operations">20.5.4. Operations</a></li></ul></li><li><a href="#rsa-oaep">20.6. RSA-OAEP</a><ul><li><a href="#rsa-oaep-description">20.6.1. Description</a></li><li><a href="#rsa-oaep-registration">20.6.2. Registration</a></li><li><a href="#rsa-oaep-params">20.6.3. RsaOaepParams dictionary</a></li><li><a href="#rsa-oaep-operations">20.6.4. Operations</a></li></ul></li><li><a href="#ecdsa">20.7. ECDSA</a><ul><li><a href="#ecdsa-description">20.7.1. Description</a></li><li><a href="#ecdsa-registration">20.7.2. Registration</a></li><li><a href="#EcdsaParams-dictionary">20.7.3. EcdsaParams dictionary</a></li><li><a href="#EcKeyGenParams-dictionary">20.7.4. EcKeyGenParams dictionary</a></li><li><a href="#EcKeyAlgorithm-dictionary">20.7.5. EcKeyAlgorithm dictionary</a></li><li><a href="#EcKeyImportParams-dictionary">20.7.6. EcKeyImportParams dictionary</a></li><li><a href="#ecdsa-operations">20.7.7. Operations</a></li></ul></li><li><a href="#ecdh">20.8. ECDH</a><ul><li><a href="#ecdh-description">20.8.1. Description</a></li><li><a href="#ecdh-registration">20.8.2. Registration</a></li><li><a href="#dh-EcdhKeyDeriveParams">20.8.3. EcdhKeyDeriveParams dictionary</a></li><li><a href="#ecdh-operations">20.8.4. Operations</a></li></ul></li><li><a href="#aes-ctr">20.9. AES-CTR</a><ul><li><a href="#aes-ctr-description">20.9.1. Description</a></li><li><a href="#aes-ctr-registration">20.9.2. Registration</a></li><li><a href="#aes-ctr-params">20.9.3. AesCtrParams dictionary</a></li><li><a href="#AesKeyAlgorithm-dictionary">20.9.4. </a></li><li><a href="#aes-keygen-params">20.9.5. AesKeyGenParams dictionary</a></li><li><a href="#aes-derivedkey-params">20.9.6. AesDerivedKeyParams dictionary</a></li><li><a href="#aes-ctr-operations">20.9.7. Operations</a></li></ul></li><li><a href="#aes-cbc">20.10. AES-CBC</a><ul><li><a href="#aes-cbc-description">20.10.1. Description</a></li><li><a href="#aes-cbc-registration">20.10.2. Registration</a></li><li><a href="#aes-cbc-params">20.10.3. AesCbcParams dictionary</a></li><li><a href="#aes-cbc-operations">20.10.4. Operations</a></li></ul></li><li><a href="#aes-cmac">20.11. AES-CMAC</a><ul><li><a href="#aes-cmac-description">20.11.1. Description</a></li><li><a href="#aes-cmac-registration">20.11.2. Registration</a></li><li><a href="#aes-cmac-params">20.11.3. AesCmacParams dictionary</a></li><li><a href="#aes-cmac-operations">20.11.4. Operations</a></li></ul></li><li><a href="#aes-gcm">20.12. AES-GCM</a><ul><li><a href="#aes-gcm-description">20.12.1. Description</a></li><li><a href="#aes-gcm-registration">20.12.2. Registration</a></li><li><a href="#aes-gcm-params">20.12.3. AesGcmParams dictionary</a></li><li><a href="#aes-gcm-operations">20.12.4. Operations</a></li></ul></li><li><a href="#aes-cfb">20.13. AES-CFB</a><ul><li><a href="#aes-cfb-description">20.13.1. Description</a></li><li><a href="#aes-cfb-registration">20.13.2. Registration</a></li><li><a href="#aes-cfb-params">20.13.3. AesCfbParams dictionary</a></li><li><a href="#aes-cfb-operations">20.13.4. Operations</a></li></ul></li><li><a href="#aes-kw">20.14. AES-KW</a><ul><li><a href="#aes-kw-description">20.14.1. Description</a></li><li><a href="#aes-kw-registration">20.14.2. Registration</a></li><li><a href="#aes-kw-operations">20.14.3. Operations</a></li></ul></li><li><a href="#hmac">20.15. HMAC</a><ul><li><a href="#hmac-description">20.15.1. Description</a></li><li><a href="#hmac-registration">20.15.2. Registration</a></li><li><a href="#hmac-importparams">20.15.3. HmacImportParams dictionary</a></li><li><a href="#HmacKeyAlgorithm-dictionary">20.15.4. HmacKeyAlgorithm dictionary</a></li><li><a href="#hmac-keygen-params">20.15.5. HmacKeyGenParams dictionary</a></li><li><a href="#hmac-derivedkey-params">20.15.6. HmacDerivedKeyParams dictionary</a></li><li><a href="#hmac-operations">20.15.7. Operations</a></li></ul></li><li><a href="#dh">20.16. Diffie-Hellman</a><ul><li><a href="#dh-description">20.16.1. Description</a></li><li><a href="#dh-registration">20.16.2. Registration</a></li><li><a href="#dh-DhKeyGenParams">20.16.3. DhKeyGenParams dictionary</a></li><li><a href="#dh-DhKeyAlgorithm">20.16.4. DhKeyAlgorithm dictionary</a></li><li><a href="#dh-DhKeyDeriveParams">20.16.5. DhKeyDeriveParams dictionary</a></li><li><a href="#dh-DhImportKeyParams">20.16.6. DhImportKeyParams dictionary</a></li><li><a href="#dh-operations">20.16.7. Operations</a></li></ul></li><li><a href="#sha">20.17. SHA</a><ul><li><a href="#sha-description">20.17.1. Description</a></li><li><a href="#sha-registration">20.17.2. Registration</a></li><li><a href="#sha-operations">20.17.3. Operations</a></li></ul></li><li><a href="#concatkdf">20.18. Concat KDF</a><ul><li><a href="#concatkdf-description">20.18.1. Description</a></li><li><a href="#concatkdf-registration">20.18.2. Registration</a></li><li><a href="#concat-params">20.18.3. ConcatParams dictionary</a></li><li><a href="#concat-operations">20.18.4. Operations</a></li></ul></li><li><a href="#hkdf-ctr">20.19. HKDF-CTR</a><ul><li><a href="#hkdf-ctr-description">20.19.1. Description</a></li><li><a href="#hkdf-ctr-registration">20.19.2. Registration</a></li><li><a href="#hkdf-ctr-params">20.19.3. HkdfCtrParams dictionary</a></li><li><a href="#hkdf2-ctr-operations">20.19.4. Operations</a></li></ul></li><li><a href="#pbkdf2">20.20. PBKDF2</a><ul><li><a href="#pbkdf2-description">20.20.1. Description</a></li><li><a href="#pbkdf2-registration">20.20.2. Registration</a></li><li><a href="#pbkdf2-params">20.20.3. Pbkdf2Params dictionary</a></li><li><a href="#pbkdf2-operations">20.20.4. Operations</a></li></ul></li></ul></li><li><a href="#algorithm-normalizing-rules">21. Algorithm normalizing rules</a></li><li><a href="#examples-section">22. JavaScript Example Code</a><ul><li><a href="#examples-signing">22.1. Generate a signing key pair, sign some data</a></li><li><a href="#examples-symmetric-encryption">22.2. Symmetric Encryption</a></li></ul></li><li><a href="#iana-section">23. IANA Considerations</a><ul><li><a href="#iana-section-jws-jwa">23.1. JSON Web Signature and Encryption Algorithms Registration</a></li><li><a href="#iana-section-jwk">23.2. JSON Web Key Parameters Registration</a></li></ul></li><li><a href="#acknowledgements-section">24. Acknowledgements</a></li><li><a href="#references">25. References</a><ul><li><a href="#normative-references">25.1. Normative References</a></li><li><a href="#informative-references">25.2. Informative References</a></li></ul></li></ul><ul><li><a href="#jwk-mapping">A. Mapping between JSON Web Key / JSON Web Algorithm</a><ul><li><a href="#jwk-mapping-alg">A.1. Algorithm mappings</a></li><li><a href="#jwk-mapping-usage">A.2. Usage mapping</a></li></ul></li><li><a href="#spki-mapping">B. Mapping between Algorithm and SubjectPublicKeyInfo</a></li><li><a href="#pkcs8-mapping">C. Mapping between Algorithm and PKCS#8 PrivateKeyInfo</a></li></ul></div>
+ <div class="toc"><ul><li><a href="#introduction">1. Introduction</a></li><li><a href="#use-cases">2. Use Cases</a><ul><li><a href="#multifactor-authentication">2.1. Multi-factor Authentication</a></li><li><a href="#protected-document">2.2. Protected Document Exchange</a></li><li><a href="#cloud-storage">2.3. Cloud Storage</a></li><li><a href="#document-signing">2.4. Document Signing</a></li><li><a href="#data-integrity-protection">2.5. Data Integrity Protection</a></li><li><a href="#secure-messaging">2.6. Secure Messaging</a></li><li><a href="#jose">2.7. Javascript Object Signing and Encryption (JOSE)</a></li></ul></li><li><a href="#conformance">3. Conformance</a></li><li><a href="#scope">4. Scope</a><ul><li><a href="#scope-abstraction">4.1. Level of abstraction</a></li><li><a href="#scope-algorithms">4.2. Cryptographic algorithms</a></li><li><a href="#scope-operations">4.3. Operations</a></li><li><a href="#scope-out-of-scope">4.4. Out of scope</a></li></ul></li><li><a href="#concepts">5. Concepts</a><ul><li><a href="#concepts-underlying-implementation">5.1. Underlying Cryptographic Implementation</a></li><li><a href="#concepts-key-storage">5.2. Key Storage</a></li></ul></li><li><a href="#security">6. Security considerations</a><ul><li><a href="#security-implementers">6.1. Security considerations for implementers</a></li><li><a href="#security-developers">6.2. Security considerations for authors</a></li><li><a href="#security-users">6.3. Security considerations for users</a></li></ul></li><li><a href="#privacy">7. Privacy considerations</a></li><li><a href="#dependencies">8. Dependencies</a></li><li><a href="#terminology">9. Terminology</a></li><li><a href="#RandomSource-interface">10. RandomSource interface</a><ul><li><a href="#RandomSource-description">10.1. Description</a></li><li><a href="#RandomSource-interface-methods">10.2. Methods and Parameters</a><ul><li><a href="#RandomSource-method-getRandomValues">10.2.1. The getRandomValues method</a></li></ul></li></ul></li><li><a href="#algorithm-dictionary">11. Algorithm dictionary</a><ul><li><a href="#algorithm-dictionary-members">11.1. Algorithm Dictionary Members</a></li></ul></li><li><a href="#key-algorithm-dictionary">12. KeyAlgorithm dictionary</a><ul><li><a href="#key-algorithm-dictionary-description">12.1. Description</a></li><li><a href="#key-algorithm-dictionary-members">12.2. KeyAlgorithm dictionary members</a></li></ul></li><li><a href="#cryptokey-interface">13. CryptoKey interface</a><ul><li><a href="#cryptokey-interface-description">13.1. Description</a></li><li><a href="#cryptokey-interface-types">13.2. Key interface data types</a></li><li><a href="#cryptokey-interface-internal-slots">13.3. CryptoKey internal slots</a></li><li><a href="#cryptokey-interface-members">13.4. CryptoKey interface members</a></li><li><a href="#cryptokey-interface-clone">13.5. Structured clone algorithm</a></li></ul></li><li><a href="#crypto-interface">14. Crypto interface</a></li><li><a href="#subtlecrypto-interface">15. SubtleCrypto interface</a><ul><li><a href="#subtlecrypto-interface-description">15.1. Description</a></li><li><a href="#subtlecrypto-interface-datatypes">15.2. Data Types</a></li><li><a href="#subtlecrypto-interface-methods">15.3. Methods and Parameters</a><ul><li><a href="#SubtleCrypto-method-encrypt">15.3.1. The encrypt method</a></li><li><a href="#SubtleCrypto-method-decrypt">15.3.2. The decrypt method</a></li><li><a href="#SubtleCrypto-method-sign">15.3.3. The sign method</a></li><li><a href="#SubtleCrypto-method-verify">15.3.4. The verify method</a></li><li><a href="#SubtleCrypto-method-digest">15.3.5. The digest method</a></li><li><a href="#SubtleCrypto-method-generateKey">15.3.6. The generateKey method</a></li><li><a href="#SubtleCrypto-method-deriveKey">15.3.7. The deriveKey method</a></li><li><a href="#SubtleCrypto-method-deriveBits">15.3.8. The deriveBits method</a></li><li><a href="#SubtleCrypto-method-importKey">15.3.9. The importKey method</a></li><li><a href="#SubtleCrypto-method-exportKey">15.3.10. The exportKey method</a></li><li><a href="#SubtleCrypto-method-wrapKey">15.3.11. The wrapKey method</a></li><li><a href="#SubtleCrypto-method-unwrapKey">15.3.12. The unwrapKey method</a></li></ul></li><li><a href="#SubtleCrypto-Exceptions">15.4. Exceptions</a></li></ul></li><li><a href="#JsonWebKey-dictionary">16. JsonWebKey dictionary</a></li><li><a href="#WorkerCrypto-interface">17. WorkerCrypto interface</a><ul><li><a href="#WorkerCrypto-description">17.1. Description</a></li></ul></li><li><a href="#big-integer">18. BigInteger</a></li><li><a href="#keypair">19. CryptoKeyPair dictionary</a></li><li><a href="#algorithms">20. Algorithms</a><ul><li><a href="#algorithm-overview">20.1. Overview</a></li><li><a href="#algorithm-concepts">20.2. Concepts</a><ul><li><a href="#algorithm-concepts-naming">20.2.1. Naming</a></li><li><a href="#algorithm-concepts-operations">20.2.2. Supported Operations</a></li><li><a href="#algorithm-concepts-normalization">20.2.3. Normalization</a></li></ul></li><li><a href="#algorithm-conventions">20.3. Specification Conventions</a></li><li><a href="#algorithm-normalizing">20.4. Algorithm Normalization</a><ul><li><a href="#algorithm-normalizing-description">20.4.1. Description</a></li><li><a href="#algorithm-normalizing-internal">20.4.2. Internal State Objects</a></li><li><a href="#algorithm-normalizing-define-an-algorithm">20.4.3. Defining an Algorithm</a></li><li><a href="#algorithm-normalizing-define-an-alias">20.4.4. Defining an Alias</a></li><li><a href="#algorithm-normalizing-normalize-an-algorithm">20.4.5. Normalizing an algorithm</a></li></ul></li><li><a href="#algorithm-recommendations">20.5. Recommendations</a><ul><li><a href="#algorithm-recommendations-authors">20.5.1. For Authors</a></li><li><a href="#algorithm-recommendations-implementers">20.5.2. For Implementers</a></li></ul></li></ul></li><li><a href="#algorithm-overview">21. Algorithm Overview</a></li><li><a href="#rsassa-pkcs1">22. RSASSA-PKCS1-v1_5</a><ul><li><a href="#rsassa-pkcs1-description">22.1. Description</a></li><li><a href="#rsassa-pkcs1-registration">22.2. Registration</a></li><li><a href="#RsaHashedKeyGenParams-dictionary">22.3. RsaHashedKeyGenParams dictionary</a></li><li><a href="#RsaHashedKeyAlgorithm-dictionary">22.4. RsaHashedKeyAlgorithm dictionary</a></li><li><a href="#RsaHashedImportParams-dictionary">22.5. RsaHashedImportParams dictionary</a></li><li><a href="#rsassa-pkcs1-operations">22.6. Operations</a></li></ul></li><li><a href="#rsa-pss">23. RSA-PSS</a><ul><li><a href="#rsa-pss-description">23.1. Description</a></li><li><a href="#rsa-pss-registration">23.2. Registration</a></li><li><a href="#RsaPssParams-dictionary">23.3. RsaPssParams dictionary</a></li><li><a href="#rsa-pss-operations">23.4. Operations</a></li></ul></li><li><a href="#rsa-oaep">24. RSA-OAEP</a><ul><li><a href="#rsa-oaep-description">24.1. Description</a></li><li><a href="#rsa-oaep-registration">24.2. Registration</a></li><li><a href="#rsa-oaep-params">24.3. RsaOaepParams dictionary</a></li><li><a href="#rsa-oaep-operations">24.4. Operations</a></li></ul></li><li><a href="#ecdsa">25. ECDSA</a><ul><li><a href="#ecdsa-description">25.1. Description</a></li><li><a href="#ecdsa-registration">25.2. Registration</a></li><li><a href="#EcdsaParams-dictionary">25.3. EcdsaParams dictionary</a></li><li><a href="#EcKeyGenParams-dictionary">25.4. EcKeyGenParams dictionary</a></li><li><a href="#EcKeyAlgorithm-dictionary">25.5. EcKeyAlgorithm dictionary</a></li><li><a href="#EcKeyImportParams-dictionary">25.6. EcKeyImportParams dictionary</a></li><li><a href="#ecdsa-operations">25.7. Operations</a></li></ul></li><li><a href="#ecdh">26. ECDH</a><ul><li><a href="#ecdh-description">26.1. Description</a></li><li><a href="#ecdh-registration">26.2. Registration</a></li><li><a href="#dh-EcdhKeyDeriveParams">26.3. EcdhKeyDeriveParams dictionary</a></li><li><a href="#ecdh-operations">26.4. Operations</a></li></ul></li><li><a href="#aes-ctr">27. AES-CTR</a><ul><li><a href="#aes-ctr-description">27.1. Description</a></li><li><a href="#aes-ctr-registration">27.2. Registration</a></li><li><a href="#aes-ctr-params">27.3. AesCtrParams dictionary</a></li><li><a href="#AesKeyAlgorithm-dictionary">27.4. </a></li><li><a href="#aes-keygen-params">27.5. AesKeyGenParams dictionary</a></li><li><a href="#aes-derivedkey-params">27.6. AesDerivedKeyParams dictionary</a></li><li><a href="#aes-ctr-operations">27.7. Operations</a></li></ul></li><li><a href="#aes-cbc">28. AES-CBC</a><ul><li><a href="#aes-cbc-description">28.1. Description</a></li><li><a href="#aes-cbc-registration">28.2. Registration</a></li><li><a href="#aes-cbc-params">28.3. AesCbcParams dictionary</a></li><li><a href="#aes-cbc-operations">28.4. Operations</a></li></ul></li><li><a href="#aes-cmac">29. AES-CMAC</a><ul><li><a href="#aes-cmac-description">29.1. Description</a></li><li><a href="#aes-cmac-registration">29.2. Registration</a></li><li><a href="#aes-cmac-params">29.3. AesCmacParams dictionary</a></li><li><a href="#aes-cmac-operations">29.4. Operations</a></li></ul></li><li><a href="#aes-gcm">30. AES-GCM</a><ul><li><a href="#aes-gcm-description">30.1. Description</a></li><li><a href="#aes-gcm-registration">30.2. Registration</a></li><li><a href="#aes-gcm-params">30.3. AesGcmParams dictionary</a></li><li><a href="#aes-gcm-operations">30.4. Operations</a></li></ul></li><li><a href="#aes-cfb">31. AES-CFB</a><ul><li><a href="#aes-cfb-description">31.1. Description</a></li><li><a href="#aes-cfb-registration">31.2. Registration</a></li><li><a href="#aes-cfb-params">31.3. AesCfbParams dictionary</a></li><li><a href="#aes-cfb-operations">31.4. Operations</a></li></ul></li><li><a href="#aes-kw">32. AES-KW</a><ul><li><a href="#aes-kw-description">32.1. Description</a></li><li><a href="#aes-kw-registration">32.2. Registration</a></li><li><a href="#aes-kw-operations">32.3. Operations</a></li></ul></li><li><a href="#hmac">33. HMAC</a><ul><li><a href="#hmac-description">33.1. Description</a></li><li><a href="#hmac-registration">33.2. Registration</a></li><li><a href="#hmac-importparams">33.3. HmacImportParams dictionary</a></li><li><a href="#HmacKeyAlgorithm-dictionary">33.4. HmacKeyAlgorithm dictionary</a></li><li><a href="#hmac-keygen-params">33.5. HmacKeyGenParams dictionary</a></li><li><a href="#hmac-derivedkey-params">33.6. HmacDerivedKeyParams dictionary</a></li><li><a href="#hmac-operations">33.7. Operations</a></li></ul></li><li><a href="#dh">34. Diffie-Hellman</a><ul><li><a href="#dh-description">34.1. Description</a></li><li><a href="#dh-registration">34.2. Registration</a></li><li><a href="#dh-DhKeyGenParams">34.3. DhKeyGenParams dictionary</a></li><li><a href="#dh-DhKeyAlgorithm">34.4. DhKeyAlgorithm dictionary</a></li><li><a href="#dh-DhKeyDeriveParams">34.5. DhKeyDeriveParams dictionary</a></li><li><a href="#dh-DhImportKeyParams">34.6. DhImportKeyParams dictionary</a></li><li><a href="#dh-operations">34.7. Operations</a></li></ul></li><li><a href="#sha">35. SHA</a><ul><li><a href="#sha-description">35.1. Description</a></li><li><a href="#sha-registration">35.2. Registration</a></li><li><a href="#sha-operations">35.3. Operations</a></li></ul></li><li><a href="#concatkdf">36. Concat KDF</a><ul><li><a href="#concatkdf-description">36.1. Description</a></li><li><a href="#concatkdf-registration">36.2. Registration</a></li><li><a href="#concat-params">36.3. ConcatParams dictionary</a></li><li><a href="#concat-operations">36.4. Operations</a></li></ul></li><li><a href="#hkdf-ctr">37. HKDF-CTR</a><ul><li><a href="#hkdf-ctr-description">37.1. Description</a></li><li><a href="#hkdf-ctr-registration">37.2. Registration</a></li><li><a href="#hkdf-ctr-params">37.3. HkdfCtrParams dictionary</a></li><li><a href="#hkdf2-ctr-operations">37.4. Operations</a></li></ul></li><li><a href="#pbkdf2">38. PBKDF2</a><ul><li><a href="#pbkdf2-description">38.1. Description</a></li><li><a href="#pbkdf2-registration">38.2. Registration</a></li><li><a href="#pbkdf2-params">38.3. Pbkdf2Params dictionary</a></li><li><a href="#pbkdf2-operations">38.4. Operations</a></li></ul></li><li><a href="#examples-section">39. JavaScript Example Code</a><ul><li><a href="#examples-signing">39.1. Generate a signing key pair, sign some data</a></li><li><a href="#examples-symmetric-encryption">39.2. Symmetric Encryption</a></li></ul></li><li><a href="#iana-section">40. IANA Considerations</a><ul><li><a href="#iana-section-jws-jwa">40.1. JSON Web Signature and Encryption Algorithms Registration</a></li><li><a href="#iana-section-jwk">40.2. JSON Web Key Parameters Registration</a></li></ul></li><li><a href="#acknowledgements-section">41. Acknowledgements</a></li><li><a href="#references">42. References</a><ul><li><a href="#normative-references">42.1. Normative References</a></li><li><a href="#informative-references">42.2. Informative References</a></li></ul></li></ul><ul><li><a href="#jwk-mapping">A. Mapping between JSON Web Key / JSON Web Algorithm</a><ul><li><a href="#jwk-mapping-alg">A.1. Algorithm mappings</a></li><li><a href="#jwk-mapping-usage">A.2. Usage mapping</a></li></ul></li><li><a href="#spki-mapping">B. Mapping between Algorithm and SubjectPublicKeyInfo</a></li><li><a href="#pkcs8-mapping">C. Mapping between Algorithm and PKCS#8 PrivateKeyInfo</a></li></ul></div>
</div>
<div id="sections">
@@ -930,8 +930,9 @@
specify the desired operation.
</p>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-<span class="comment">// TBD: <a href="http://www.w3.org/2012/webcrypto/track/issues/28">ISSUE-28</a></span>
-typedef (<a href="#dfn-Algorithm">Algorithm</a> or DOMString) <dfn id="dfn-AlgorithmIdentifier">AlgorithmIdentifier</dfn>;
+typedef (object or DOMString) <dfn id="dfn-AlgorithmIdentifier">AlgorithmIdentifier</dfn>;
+
+typedef <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> <dfn id="dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</dfn>;
dictionary <dfn id="dfn-Algorithm">Algorithm</dfn> {
DOMString <a href="#dfn-Algorithm-name">name</a>;
@@ -1309,6 +1310,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>encrypt</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1329,28 +1344,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>key</var> and <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the
- encrypt operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>key</var> does not contain an entry that is <code>"encrypt"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
</p>
@@ -1398,6 +1391,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>decrypt</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1418,28 +1425,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>key</var> and <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the decrypt
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>key</var> does not contain an entry that is <code>"decrypt"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
</p>
@@ -1486,6 +1471,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>sign</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1506,28 +1505,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>key</var> and <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the sign
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>key</var> does not contain an entry that is <code>"sign"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
</p>
@@ -1572,6 +1549,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>verify</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>data</var> be the result of <a href="#concept-clone-CryptoOperationData">
cloning the data</a> of the <code>data</code> parameter passed to the
<a href="#dfn-SubtleCrypto-method-verify">verify</a> method.
@@ -1599,28 +1590,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>key</var>, <var>data</var> and <var>signature</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the verify
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>key</var> does not contain an entry that is <code>"verify"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
</p>
@@ -1666,6 +1635,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>digest</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1686,28 +1669,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the digest
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
Let <var>result</var> be the result of performing the digest
operation specified by <var>normalizedAlgorithm</var> using
<var>algorithm</var>, with <var>data</var>
@@ -1742,6 +1703,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>generateKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1762,28 +1737,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>extractable</var> and <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the generate
- key operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If <var>usages</var> includes a value that is not a
<a href="#dfn-RecognizedKeyUsage">recognized key usage value</a>,
then <a href="#concept-return-an-error">return an error</a> named
@@ -1826,6 +1779,34 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>deriveKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>normalizedDerivedKeyAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>derivedKeyType</var> and <code>op</code> set to
+ <code>importKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1846,39 +1827,17 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>baseKey</var>, <var>extractable</var> and <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the derive bits
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedDerivedKeyAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>derivedKeyType</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
+ <var>normalizedAlgorithm</var> does not identify a <a href="#algorithms">registered algorithm</a> that supports the derive bits
+ operation, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
<li>
<p>
If the <a href="#dfn-Algorithm-name">name</a> member of
<var>normalizedDerivedKeyAlgorithm</var> does not identify a
<a href="#algorithms">registered algorithm</a> that supports the get key length
- and import key operations, then <a href="#concept-return-an-error">return an error</a> named
+ operation, then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
</p>
</li>
@@ -1948,6 +1907,20 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>deriveBits</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -1968,28 +1941,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>baseKey</var> and <var>length</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the derive bits
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>baseKey</var> does not contain an entry that is <code>"deriveBits"</code>,
then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
@@ -2030,6 +1981,20 @@
</p>
</li>
<li>
+ <p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>importKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
<dl class="switch">
<dt>
If <var>format</var> is equal to the string <code>raw</code>,
@@ -2072,29 +2037,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>format</var>, <var>keyData</var>,
- <var>extractable</var> and <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the import key
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If <var>format</var> is not
a <a href="#dfn-RecognizedKeyFormats">recognized key
format value</a>, then <a href="#concept-return-an-error">return an error</a> named
@@ -2161,19 +2103,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>format</var> and <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
If <var>format</var> is not a
<a href="#dfn-RecognizedKeyFormats">recognized key
format value</a>, then <a href="#concept-return-an-error">return an error</a> named
@@ -2182,11 +2111,9 @@
</li>
<li>
<p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the export key
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ If the <a href="#dfn-Algorithm-name">name</a> member of of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> does not identify a <a href="#algorithms">registered algorithm</a>
+ that supports the export key operation, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
</p>
</li>
<li>
@@ -2229,6 +2156,28 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>wrapKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>encrypt</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -2249,19 +2198,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>format</var>, <var>key</var> and <var>wrappingKey</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
If the <a href="#dfn-Algorithm-name">name</a> member of
<var>normalizedAlgorithm</var> does not identify a
<a href="#algorithms">registered algorithm</a> that supports the encrypt or wrap
@@ -2423,6 +2359,42 @@
</li>
<li>
<p>
+ Let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>unwrapKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, let <var>normalizedAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>algorithm</var> and <code>op</code> set to
+ <code>decrypt</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>normalizedKeyAlgorithm</var> be the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>, with
+ <code>alg</code> set to <var>unwrappedKeyAlgorithm</var> and <code>op</code> set to
+ <code>importKey</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred, return a Promise rejected with
+ <var>normalizedKeyAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>promise</var> be a new Promise object and <var>resolver</var> its
associated resolver object.
</p>
@@ -2443,46 +2415,6 @@
</li>
<li>
<p>
- Perform type mapping as specified in [<a href="#WebIDL">WEBIDL</a>] for
- <var>format</var>, <var>wrappedKey</var>, <var>unwrappingKey</var>,
- <var>extractable</var> and <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the unwrap key or
- decrypt
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedKeyAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>unwrappedKeyAlgorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedKeyAlgorithm</var> does not identify a
- <a href="#algorithms">registered algorithm</a> that supports the importKey
- operation, then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
If the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
<var>unwrappingKey</var> does not contain an entry that is
<code>"unwrapKey"</code>, then <a href="#concept-return-an-error">return an
@@ -2741,6 +2673,475 @@
<div id="algorithms" class="section">
<h2>20. Algorithms</h2>
+ <div id="algorithm-overview" class="section">
+ <h3>20.1. Overview</h3>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ In addition to providing a common interface to perform cryptographic operations, by
+ way of the <a href="#dfn-SubtleCrypto">SubtleCrypto</a> interface, this specification
+ also provides descriptions for a variety of algorithms that authors may wish to use and
+ that User Agents may choose to implement. This includes a selection of commonly-deployed
+ symmetric and asymmetric algorithms, key derivation mechanisms, and methods for wrapping
+ and unwrapping keys. Further, this specification defines a process to allow additional
+ specifications to introduce additional cryptographic algorithms.
+ </p>
+ </div>
+
+ <div id="algorithm-concepts" class="section">
+ <h3>20.2. Concepts</h3>
+ <div id="algorithm-concepts-naming" class="section">
+ <h4>20.2.1. Naming</h4>
+ <p>
+ Every cryptographic algorithm defined for use with the Web Cryptography API
+ <span class="RFC2119">MUST</span> have a unique name, referred to as its
+ <dfn id="recognized-algorithm-name">recognized algorithm name</dfn>, such that no
+ other specification defines the same case-sensitive string for use with the
+ Web Cryptography API.
+ </p>
+ </div>
+ <div id="algorithm-concepts-operations" class="section">
+ <h4>20.2.2. Supported Operations</h4>
+ <p>
+ Every cryptographic algorithm defined for use with the Web Cryptography API has a list
+ of <dfn id="supported-operation">supported operations</dfn>, which are a set of
+ sub-algorithms to be invoked by the <a href="#dfn-SubtleCrypto">SubtleCrypto</a>
+ interface in order to perform the desired cryptographic operation. This specification
+ makes use of the following operations:
+ </p>
+ <ul>
+ <li>encrypt</li>
+ <li>decrypt</li>
+ <li>sign</li>
+ <li>verify</li>
+ <li>deriveBits</li>
+ <li>wrapKey</li>
+ <li>unwrapKey</li>
+ <li>generateKey</li>
+ <li>importKey</li>
+ <li>exportKey</li>
+ <li>getLength</li>
+ </ul>
+ <p>
+ If a given algorithm specification does not list a particular operation as supported,
+ or explicitly lists an operation as not-supported, then the User Agent
+ <span class="RFC2119">MUST</span> behave as if the invocation of the sub-algorithm
+ threw a NotSupportedError.
+ </p>
+ </div>
+ <div id="algorithm-concepts-normalization" class="section">
+ <h4>20.2.3. Normalization</h4>
+ <p>
+ Every cryptographic algorithm defined for use with the Web Cryptography API <span class="RFC2119">MUST</span> define, for every <a href="#supported-operation">
+ supported operation</a>, the IDL type to use for <a href="#concept-algorithm-normalization">algorithm normalization</a>, as well as the
+ IDL type or types of the return values of the sub-algorithms.
+ </p>
+ </div>
+ </div>
+
+ <div id="algorithm-conventions" class="section">
+ <h3>20.3. Specification Conventions</h3>
+ <p>
+ Every cryptographic algorithm definition within this specification employs the following
+ specification conventions. A section, titled <em>"Registration"</em>, will include the
+ <a href="#recognized-algorithm-name">recognized algorithm name</a>. Additionally, it
+ includes a table, which will list each of the <a href="#supported-operation">supported
+ operations</a> as rows, identified by the <em>Operation</em> column. The contents of the
+ <em>Parameters</em> column for a given row will contain the IDL type to use for <a href="#concept-algorithm-normalization">algorithm normalization</a> for that operation,
+ and the contents of the <em>Result</em> column for that row indicate the IDL type that
+ results from performing the supported operation.
+ </p>
+ <p>
+ If a conforming User Agent implements an algorithm, it
+ <span class="RFC2119">MUST</span> implement all of the <a href="#supported-operation">
+ supported operations</a> and <span class="RFC2119">MUST</span> return the IDL type
+ specified.
+ </p>
+ <p>
+ Additionally, upon initialization, conforming User Agents must perform the
+ <a href="#concept-define-an-algorithm">define an algorithm</a> steps for each of
+ the supported operations, registering their IDL parameter type as indicated.
+ </p>
+ </div>
+
+ <div id="algorithm-normalizing" class="section">
+ <h3>20.4. Algorithm Normalization</h3>
+ <div id="algorithm-normalizing-description" class="section">
+ <h4>20.4.1. Description</h4>
+ <p class="norm">This section is non-normative</p>
+ <p>
+ The <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> typedef permits
+ algorithms to either be specified as a <a href="#dfn-DOMString">DOMString</a> or an
+ object. The usage of <a href="#dfn-DOMString">DOMString</a> is to permit authors a
+ short-hand for noting algorithms that have no parameters (e.g. SHA-1), as well as to
+ permit 'aliases' for well-known configurations of algorithms, rather than require
+ authors explicitly specify all of the parameters. The usage of object is to allow an <a href="#dfn-Algorithm">Algorithm</a> (or appropriate subclass) to be specified, which
+ contains all of the associated parameters for an object.
+ </p>
+ <p>
+ Because of this, it's necessary to define the algorithm for converting an <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> into an appropriate dictionary
+ that is usable with this API. This algorithm must be extensible, so as to allow new
+ cryptographic algorithms to be added, and consistent, so that Web IDL type mapping can
+ occur before any control is returned to the calling script, which would potentially
+ allow the mutation of parameters or the script environment.
+ </p>
+ </div>
+
+ <div id="algorithm-normalizing-internal" class="section">
+ <h4>20.4.2. Internal State Objects</h4>
+ <p>
+ This specification makes use of an internal object,
+ [[<dfn id="dfn-supportedAlgorithms">supportedAlgorithms</dfn>]]. This internal object is
+ not exposed to applications.
+ </p>
+ <p>
+ Because this value is not exposed to applications, the exact type is not specified.
+ It is only required to behave as an associative container of key/value pairs, where
+ comparisons of keys are performed in a case-sensitive manner.
+ </p>
+ <p>
+ The initial contents of this internal object are as follows:
+ </p>
+ <ol>
+ <li>
+ <p>
+ For each value, <var>v</var> in the List of <a href="#supported-operation">supported operations</a>, perform the following:
+ </p>
+ <ol>
+ <li>
+ Initialize a new associative container, <var>container</var>
+ </li>
+ <li>
+ Set the <code>aliases</code> key of <var>container</var> to a new associative
+ container.
+ </li>
+ <li>
+ Set the <code>algorithms</code> key of <var>container</var> to a new associative
+ container.
+ </li>
+ <li>
+ Set the <var>v</var> key of the internal object to <var>container</var>.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ </div>
+
+ <div id="algorithm-normalizing-define-an-algorithm" class="section">
+ <h4>20.4.3. Defining an Algorithm</h4>
+ <p>
+ The <dfn id="concept-define-an-algorithm">define an algorithm</dfn> algorithm is used
+ by specification authors to indicate how a user agent should normalize arguments for a
+ particular algorithm. Its input is an algorithm name <var>alg</var>, represented as a
+ DOMString, operation name <var>op</var>, represented as a DOMString, and desired IDL
+ dictionary type <var>type</var>. The algorithm behaves as follows:
+ </p>
+ <ol>
+ <li>
+ Let <var>algorithmsAndAliases</var> be the associative container stored at the
+ <var>op</var> key of [[<a href="#dfn-supportedAlgorithms">supportedAlgorithms</a>]].
+ </li>
+ <li>
+ Let <var>registeredAlgorithms</var> be the value of the <code>algorithms</code> key of
+ <var>algorithmsAndAliases</var>.
+ </li>
+ <li>
+ Set the <var>alg</var> key of <var>registeredAlgorithms</var> to the IDL dictionary
+ type <var>type</var>.
+ </li>
+ </ol>
+ </div>
+
+ <div id="algorithm-normalizing-define-an-alias" class="section">
+ <h4>20.4.4. Defining an Alias</h4>
+ <p>
+ The <dfn id="concept-define-an-alias">define an alias</dfn> algorithm is used by
+ specification authors to indicate how a user agent should normalize aliases for
+ particular algorithms. Its input is an algorithm alias <var>alg</var>, represented as
+ a DOMString, operation name <var>op</var>, represented as a DOMString, and internal
+ IDL object <var>default</var>. The algorithm behaves as follows:
+ </p>
+ <ol>
+ <li>
+ Let <var>algorithmsAndAliases</var> be the associative container stored at the
+ <var>op</var> key of [[<a href="#dfn-supportedAlgorithms">supportedAlgorithms</a>]].
+ </li>
+ <li>
+ Let <var>registeredAlgorithms</var> be the value of the <code>algorithms</code> key of
+ <var>algorithmsAndAliases</var>.
+ </li>
+ <li>
+ Set the <var>alg</var> key of <var>registeredAlgorithms</var> to <var>default</var>.
+ </li>
+ </ol>
+ </div>
+
+ <div id="algorithm-normalizing-normalize-an-algorithm" class="section">
+ <h4>20.4.5. Normalizing an algorithm</h4>
+ <p>
+ The <dfn id="dfn-normalize-an-algorithm">normalize an algorithm</dfn> algorithm defines
+ a process for coercing inputs to a targeted IDL dictionary type, after Web IDL
+ conversion has occurred. It is designed to be extensible, to allow future specifications
+ to define additional algorithms, as well as safe for use with Promises. Its input is an
+ operation name <var>op</var> and an <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> <var>alg</var>. Its output is
+ either an IDL dictionary type or an error. It behaves as follows:
+ </p>
+ <dl class="switch">
+ <dt>If <var>alg</var> is an instance of a DOMString:</dt>
+ <dd>
+ <ol>
+ <li>
+ Let <var>algorithmsAndAliases</var> be the associative container stored at the
+ <code>op</code> key of [[<a href="#dfn-supportedAlgorithms">supportedAlgorithms</a>]].
+ </li>
+ <li>
+ If <var>algorithmAndAliases</var> is <code>undefined</code>, return a
+ new <code>NotSupportedError</code> and terminate this algorithm.
+ </li>
+ <li>
+ Let <var>registeredAliases</var> be the associative container stored at the
+ <code>aliases</code> key of <var>algorithmsAndAliases</var>.
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <var>alg</var> key of <var>registeredAliases</var> is
+ <code>undefined</code>:
+ </dt>
+ <dd>
+ Return the result of running the <a href="#dfn-normalize-an-algorithm">normalize an algorithm</a> algorithm, with
+ the <code>alg</code> set to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ dictionary whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is
+ <var>alg</var>, and with the <code>op</code> set to <var>op</var>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ Return the internal IDL object stored in the <var>alg</var> key of
+ <var>registeredAliases</var>.
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>alg</var> is an IDL object:</dt>
+ <dd>
+ <ol>
+ <li>
+ Let <var>algorithmsAndAliases</var> be the associative container stored at the
+ <code>op</code> key of [[<a href="#dfn-supportedAlgorithms">supportedAlgorithms</a>]].
+ </li>
+ <li>
+ If <var>algorithmAndAliases</var> is <code>undefined</code>, return a
+ new <code>NotSupportedError</code> and terminate this algorithm.
+ </li>
+ <li>
+ Let <var>registeredAlgorithms</var> be the associative container stored at the
+ <code>algorithms</code> key of <var>algorithmsAndAliases</var>.
+ </li>
+ <li>
+ Let <var>initialAlg</var> be the result of converting the ECMAScript object
+ represented by <var>alg</var> to the IDL dictionary type <a href="#dfn-Algorithm">Algorithm</a>, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </li>
+ <li>
+ If an error occurred, return the error and terminate this algorithm.
+ </li>
+ <li>
+ If the <a href="#dfn-Algorithm-name">name</a> attribute of <var>initialAlg</var>
+ is not present, return a new <code>SyntaxError</code> and terminate this
+ algorithm.
+ </li>
+ <li>
+ Let <var>algName</var> be the value of the <a href="#dfn-Algorithm-name">name</a>
+ attribute of <var>initialAlg</var>.
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <var>algName</var> key of <var>registeredAlgorithms</var> is
+ <code>undefined</code>:
+ </dt>
+ <dd>
+ Return a new <code>NotSupportedError</code> and terminate this algorithm.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ Let <var>desiredType</var> be the IDL dictionary type stored in the
+ <var>algName</var> key of <var>registeredAlgorithms</var>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ Let <var>normalizedAlgorithm</var> be the result of converting the ECMAScript
+ object represented by <var>alg</var> to the IDL dictionary type
+ <var>desiredType</var>, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </li>
+ <li>
+ If an error occurred, return the error and terminate this algorithm.
+ </li>
+ <li>
+ Let <var>dictionaries</var> be a list consisting of the IDL dictionary type
+ <var>desiredType</var> and all of <var>desiredType</var>'s inherited dictionaries,
+ in order from least to most derived.
+ </li>
+ <li>
+ <p>
+ For each dictionary <var>dictionary</var> in <var>dictionaries</var>:
+ </p>
+ <ol>
+ <li>
+ <p>
+ For each dictionary member <var>member</var> declared on
+ <var>dictionary</var>, in order:
+ </p>
+ <ol>
+ <li>
+ If <var>member</var> is not nullable, and is not present, return a new
+ <code>SyntaxError</code> and terminate this algorithm.
+ </li>
+ <li>
+ If <var>member</var> is nullable, and is not present, return to
+ iterating the next dictionary member <var>member</var>, stopping further
+ processing of this <var>member</var>.
+ </li>
+ <li>
+ Let <var>key</var> be the identifier of <var>member</var>.
+ </li>
+ <li>
+ Let <var>idlValue</var> be the value of the dictionary member with
+ key name of <var>key</var> on <var>normalizedAlgorithm</var>.
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>member</var> is of the type
+ <a href="#dfn-CryptoOperationData">CryptoOperationData</a> and is
+ present:
+ </dt>
+ <dd>
+ Set the dictionary member on <var>normalizedAlgorithm</var> with key
+ name <var>key</var> to a <a href="#concept-clone-CryptoOperationData">clone of
+ <var>idlValue</var></a>, replacing the current value.
+ </dd>
+ <dt>
+ If <var>member</var> is of the type
+ <a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a>:
+ </dt>
+ <dd>
+ Set the dictionary member on <var>normalizedAlgorithm</var> with key
+ name <var>key</var> to the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>,
+ with the <code>alg</code> set to <var>idlValue</var> and the
+ <code>op</code> set to <code>"digest"</code>.
+ </dd>
+ <dt>
+ If <var>member</var> is of the type
+ <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a>:
+ </dt>
+ <dd>
+ Set the dictionary member on <var>normalizedAlgorithm</var> with key
+ name <var>key</var> to the result of
+ <a href="#dfn-normalize-an-algorithm">normalizing an algorithm</a>,
+ with the <code>alg</code> set to <var>idlValue</var> and the
+ <code>op</code> set to <var>op</var>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ If an error occurred, return the error and terminate this algorithm.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ <li>
+ Return <var>normalizedAlgorithm</var>.
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+
+ </div>
+
+ <div id="algorithm-recommendations" class="section">
+ <h3>20.5. Recommendations</h3>
+ <p class="norm">This section is non-normative.</p>
+ <div id="algorithm-recommendations-authors" class="section">
+ <h4>20.5.1. For Authors</h4>
+ <p>
+ As this API is meant to be extensible, in order to keep up with future developments
+ within cryptography, there are no algorithms that conforming user agents are required
+ to implement. As such, authors should check to see what algorithms are currently
+ recommended and supported by implementations.
+ </p>
+ <p>
+ As highlighted in the <a href="#security-considerations">Security Considerations</a>,
+ even cryptographic algorithms that might be considered strong for one purpose may be
+ insufficient when used with another purpose. Authors should therefore proceed with
+ extreme caution before inventing new cryptographic protocols.
+ </p>
+ <p>
+ Additionally, this specification includes several algorithms which, in their default
+ usage, can result in cryptographic vulnerabilities. While these concerns may be
+ mitigated, such as through the combination and composition with additional algorithms
+ provided by this specification, authors should proceed with caution and review the
+ relevant cryptographic literature before using a given algorithm. The inclusion of
+ algorithms within this specification is not an indicator of their suitability for any
+ or all purpose, and instead merely serve to provide as a specification for how a
+ conforming User Agent must implement the given algorithm, if it choses to implement
+ the algorithm.
+ </p>
+ </div>
+ <div id="algorithm-recommendations-implementers" class="section">
+ <h4>20.5.2. For Implementers</h4>
+ <p>
+ In order to promote interoperability for developers, this specification includes a
+ list of suggested algorithms. These are considered to be the most widely used
+ algorithms in practice at the time of writing, and therefore provide a good starting
+ point for initial implementations of this specification. The suggested algorithms are:
+ </p>
+ <ul>
+ <li>
+ <a href="#hmac">HMAC</a> using <a href="#alg-sha-1">SHA-1</a>
+ </li>
+ <li>
+ <a href="#hmac">HMAC</a> using <a href="#alg-sha-256">SHA-256</a>
+ </li>
+ <li>
+ <a href="#rsassa-pkcs1">RSASSA-PKCS1-v1_5</a> using
+ <a href="#alg-sha-256">SHA-1</a>
+ </li>
+ <li>
+ <a href="#rsa-pss">RSA-PSS</a> using <a href="#alg-sha-256">SHA-256</a>
+ and MGF1 with <a href="#alg-sha-256">SHA-256</a>.
+ </li>
+ <li>
+ <a href="#rsa-oaep">RSA-OAEP</a> using <a href="#alg-sha-256">SHA-256</a>
+ and MGF1 with <a href="#alg-sha-256">SHA-256</a>.
+ </li>
+ <li>
+ <a href="#ecdsa">ECDSA</a> using <a href="#dfn-NamedCurve-p256">P-256</a>
+ curve and <a href="#alg-sha-256">SHA-256</a>
+ </li>
+ <li><a href="#aes-cbc">AES-CBC</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div id="algorithm-overview" class="section">
+ <h2>21. Algorithm Overview</h2>
+ <p class="norm">The following section is non-normative.</p>
+ <p>
+ The table below contains an overview of the algorithms described within this
+ specification, as well as the set of operations the algorithm may be used with.
+ </p>
+ <p class="note">
+ Application developers and script authors should not interpret this table as a
+ recommendation for the use of particular algorithms. Instead, it simply documents what
+ operations are supported. Authors should refer to the <a href="#security-developers">Security considerations for authors</a> section of this
+ document to better understand the risks and concerns that may arise when using certain
+ algorithms.
+ </p>
<div class="ednote"><div class="ednoteHeader">Editorial note</div>
<p>
Note: All algorithms listed should be considered as "features at risk",
@@ -2754,13054 +3155,12166 @@
altered in future revisions.
</p>
</div>
- <div id="algorithms-index" class="section">
- <h3>20.1. Registered algorithms</h3>
+ <table>
+ <thead>
+ <tr>
+ <th>Algorithm name</th>
+ <th scope="col">encrypt</th>
+ <th scope="col">decrypt</th>
+ <th scope="col">sign</th>
+ <th scope="col">verify</th>
+ <th scope="col">digest</th>
+ <th scope="col">generateKey</th>
+ <th scope="col">deriveKey</th>
+ <th scope="col">deriveBits</th>
+ <th scope="col">importKey</th>
+ <th scope="col">exportKey</th>
+ <th scope="col">wrapKey</th>
+ <th scope="col">unwrapKey</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><a href="#rsassa-pkcs1">RSASSA-PKCS1-v1_5</a></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#rsa-pss">RSA-PSS</a></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#rsa-oaep">RSA-OAEP</a></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#ecdsa">ECDSA</a></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#ecdh">ECDH</a></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#aes-ctr">AES-CTR</a></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#aes-cbc">AES-CBC</a></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#aes-cmac">AES-CMAC</a></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#aes-gcm">AES-GCM</a></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#aes-cfb">AES-CFB</a></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#aes-kw">AES-KW</a></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ </tr>
+ <tr>
+ <td><a href="#hmac">HMAC</a></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#dh">DH</a></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#sha">SHA-1</a></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#sha">SHA-256</a></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#sha">SHA-384</a></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#sha">SHA-512</a></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#concatkdf">CONCAT</a></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#hkdf-ctr">HKDF-CTR</a></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a href="#pbkdf2">PBKDF2</a></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✔</td>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <div id="rsassa-pkcs1" class="section">
+ <h3>22. RSASSA-PKCS1-v1_5</h3>
+ <div id="rsassa-pkcs1-description" class="section">
+ <h4>22.1. Description</h4>
+ <p>
+ The <code>"RSASSA-PKCS1-v1_5"</code> algorithm identifier is used to perform
+ signing and verification using the RSASSA-PKCS1-v1_5 algorithm specified in
+ [<cite><a href="#RFC3447">RFC3447</a></cite>].
+ </p>
+ </div>
+ <div id="rsassa-pkcs1-registration" class="section">
+ <h4>22.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"RSASSA-PKCS1-v1_5"</code>.
+ </p>
<table>
<thead>
<tr>
- <th>Algorithm name</th>
- <th scope="col">encrypt</th>
- <th scope="col">decrypt</th>
- <th scope="col">sign</th>
- <th scope="col">verify</th>
- <th scope="col">digest</th>
- <th scope="col">generateKey</th>
- <th scope="col">deriveKey</th>
- <th scope="col">deriveBits</th>
- <th scope="col">importKey</th>
- <th scope="col">exportKey</th>
- <th scope="col">wrapKey</th>
- <th scope="col">unwrapKey</th>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
</tr>
</thead>
<tbody>
<tr>
- <td><a href="#rsassa-pkcs1">RSASSA-PKCS1-v1_5</a></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#rsa-pss">RSA-PSS</a></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#rsa-oaep">RSA-OAEP</a></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#ecdsa">ECDSA</a></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#ecdh">ECDH</a></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#aes-ctr">AES-CTR</a></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#aes-cbc">AES-CBC</a></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#aes-cmac">AES-CMAC</a></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#aes-gcm">AES-GCM</a></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#aes-cfb">AES-CFB</a></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#aes-kw">AES-KW</a></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- </tr>
- <tr>
- <td><a href="#hmac">HMAC</a></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#dh">DH</a></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#sha">SHA-1</a></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#sha">SHA-256</a></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#sha">SHA-384</a></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#sha">SHA-512</a></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#concatkdf">CONCAT</a></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#hkdf-ctr">HKDF-CTR</a></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td><a href="#pbkdf2">PBKDF2</a></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✔</td>
- <td>✔</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
+ <td>sign</td>
+ <td>None</td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>verify</td>
+ <td>None</td>
+ <td>boolean</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
</tr>
</tbody>
</table>
</div>
- <div id="recommended-algorithms" class="section">
- <h3>20.2. Recommended algorithms</h3>
- <p class="norm">This section is non-normative</p>
- <p>
- As the API is meant to be extensible in order to keep up with future developments within
- cryptography and to provide flexibility, there are no strictly required algorithms. Thus
- users of this API should check to see what algorithms are currently recommended and
- supported by implementations. As highlighted in the <a href="#security">Security
- Considerations</a>, even strong cryptographic algorithms may be combined in insecure
- ways. Users should therefore proceed with extreme caution when inventing new
- cryptographic protocols.
- </p>
- <p>
- Implementers should carefully review their support for different algorithms based on the
- evolving state of the cryptographic literature. It is expected that the set of
- widely-accepted algorithms will change over time as new advances are made.
- </p>
- <p>
- With the above caveats in mind, in order to promote interoperability for developers,
- this specification includes a list of suggested algorithms. These are considered to be
- the most widely used algorithms in practice at the time of writing, and therefore
- provide a good starting point for initial implementations of this specification. The
- suggested algorithms are:
- </p>
- <ul>
- <li>
- <a href="#hmac">HMAC</a> using <a href="#alg-sha-1">SHA-1</a>
- </li>
- <li>
- <a href="#hmac">HMAC</a> using <a href="#alg-sha-256">SHA-256</a>
- </li>
- <li>
- <a href="#rsassa-pkcs1">RSASSA-PKCS1-v1_5</a> using
- <a href="#alg-sha-256">SHA-1</a>
- </li>
- <li>
- <a href="#rsa-pss">RSA-PSS</a> using <a href="#alg-sha-256">SHA-256</a>
- and MGF1 with <a href="#alg-sha-256">SHA-256</a>.
- </li>
- <li>
- <a href="#rsa-oaep">RSA-OAEP</a> using <a href="#alg-sha-256">SHA-256</a>
- and MGF1 with <a href="#alg-sha-256">SHA-256</a>.
- </li>
- <li>
- <a href="#ecdsa">ECDSA</a> using <a href="#dfn-NamedCurve-p256">P-256</a>
- curve and <a href="#alg-sha-256">SHA-256</a>
- </li>
- <li><a href="#aes-cbc">AES-CBC</a></li>
- </ul>
- <p>
- To see the results of test-cases between implementations, please see the [@@Upcoming]
- Web Cryptography Test Cases Working Group.
- </p>
- </div>
- <div id="defining-an-algorithm" class="section">
- <h3>20.3. Defining an algorithm</h3>
- <p>
- Each algorithm that is to be exposed via the Web Cryptography API
- <span class="RFC2119">SHOULD</span> be registered via the Web Cryptography working group,
- and <span class="RFC2119">MUST</span> include all of the following details. Algorithms
- that are not registered via these means, but are exposed via this API,
- <span class="RFC2119">MUST</span> be processed as if the sections had been defined.
- </p>
- <div id="recognized-algorithm-name" class="section">
- <h4>20.3.1. Recognized algorithm name</h4>
- <p>
- Each registered algorithm <span class="RFC2119">MUST</span> have a canonical name
- for which applications can refer to the algorithm. The canonical name
- <span class="RFC2119">MUST</span> contain only ASCII characters and
- <span class="RFC2119">MUST NOT</span> equal any other canonical name or
- <a href="#dfn-algorithm-alias">algorithm alias</a> when every character in both names
- are converted to lower case.
- </p>
- </div>
- <div id="supported-operations" class="section">
- <h4>20.3.2. Supported operations</h4>
- <p>
- Each registered algorithm <span class="RFC2119">MUST</span> define the operations
- that it supports.
- </p>
- </div>
- <div id="algorithm-specific-params" class="section">
- <h4>20.3.3. Algorithm-specific parameters</h4>
- <p>
- Each registered algorithm <span class="RFC2119">MUST</span> define the expected
- parameters, if any, that should be exposed via the <a href="#dfn-Algorithm">Algorithm</a>
- dictionary for every <a href="#supported-operations">supported operation</a>.
- </p>
- </div>
- <div id="algorithm-result" class="section">
- <h4>20.3.4. Algorithm results</h4>
- <p>
- Each registered algorithm <span class="RFC2119">MUST</span> define the contents
- of the result of performing the underlying cryptographic operation for every
- <a href="#supported-operations">supported operation</a>.
- </p>
- </div>
- <div id="algorithm-alias" class="section">
- <h4>20.3.5. <dfn id="dfn-algorithm-alias">Algorithm aliases</dfn></h4>
- <p>
- Each registered algorithm <span class="RFC2119">MAY</span> define one or more aliases
- that may define a fully normalized <a href="#dfn-Algorithm">Algorithm</a> object.
- </p>
- <p>
- Each algorithm alias <span class="RFC2119">MUST</span> follow the same naming rules
- as the <a href="#recognized-algorithm-name">recognized algorithm name</a>.
- </p>
- </div>
- </div>
-
- <div id="rsassa-pkcs1" class="section">
- <h3>20.4. RSASSA-PKCS1-v1_5</h3>
- <div id="rsassa-pkcs1-description" class="section">
- <h4>20.4.1. Description</h4>
- <p>
- The <code>"RSASSA-PKCS1-v1_5"</code> algorithm identifier is used to perform
- signing and verification using the RSASSA-PKCS1-v1_5 algorithm specified in
- [<cite><a href="#RFC3447">RFC3447</a></cite>].
- </p>
- </div>
- <div id="rsassa-pkcs1-registration" class="section">
- <h4>20.4.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"RSASSA-PKCS1-v1_5"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>sign</td>
- <td>None</td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>verify</td>
- <td>None</td>
- <td>boolean</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="RsaHashedKeyGenParams-dictionary" class="section">
- <h4>20.4.3. RsaHashedKeyGenParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+ <div id="RsaHashedKeyGenParams-dictionary" class="section">
+ <h4>22.3. RsaHashedKeyGenParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</dfn> : <a href="#dfn-RsaKeyGenParams">RsaKeyGenParams</a> {
- <span class="comment">// The hash algorithm to use</span>
- <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> <dfn id="dfn-RsaHashedKeyGenParams-hash">hash</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="RsaHashedKeyAlgorithm-dictionary" class="section">
- <h4>20.4.4. RsaHashedKeyAlgorithm dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</dfn> : <a href="#dfn-RsaKeyAlgorithm">RsaKeyAlgorithm</a> {
- <span class="comment">// The hash algorithm that is used with this key</span>
- <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> <dfn id="dfn-RsaHashedKeyAlgorithm-hash">hash</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="RsaHashedImportParams-dictionary" class="section">
- <h4>20.4.5. RsaHashedImportParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-RsaHashedImportParams">RsaHashedImportParams</dfn> {
- <span class="comment">// The hash algorithm to use</span>
- <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> <dfn id="dfn-RsaHashedImportParams-hash">hash</dfn>;
+<span class="comment">// The hash algorithm to use</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-RsaHashedKeyGenParams-hash">hash</dfn>;
};
- </code></pre></div></div>
- <div class="ednote"><div class="ednoteHeader">Editorial note</div>
- <p>
- Should this be folded into RsaHashedKeyGenParams and rely on the optional nature of the
- dictionary fields?
- </p>
- </div>
- </div>
- <div id="rsassa-pkcs1-operations" class="section">
- <h4>20.4.6. Operations</h4>
- <dl>
- <dt>Sign</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the signature generation operation defined in Section 8.2 of [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- as the signer's private key and the <a href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
- <var>M</var> and using the hash function specified in the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>signature</var> be the value <var>S</var> that results from
- performing the operation.
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Verify</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the signature verification operation defined in Section 8.2 of
- [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the
- [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> as the signer's RSA public key and the <a href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
- <var>M</var> and the <a href="#concept-contents-of-arraybuffer">contents of
- <var>signature</var></a> as <var>S</var> and using the hash function specified
- in the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
- [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a boolean with value true if the
- result of the operations was "valid signature" and a boolean with value
- false otherwise.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a> are not present
- in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an RSA key pair, as defined in [<cite><a href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> attribute of
- <var>normalizedAlgorithm</var> and RSA public exponent equal to the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> attribute of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If generation of the key pair fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSASSA-PKCS1-v1_5"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
- attribute of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
- attribute of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
- of <var>algorithm</var> to equal the
- <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the <a href="#concept-usage-intersection">usage
- intersection</a> of <var>usages</var> and <code>[ "verify" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
- intersection</a> of <var>usages</var> and <code>[ "sign" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to be <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to be <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object, as
- defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- <div class="ednote"><div class="ednoteHeader">Editorial note</div>
- <p>
- TODO: Specify the mapping between key.algorithm.hash and the appropriate Hash
- functions (and back to OID).
- </p>
- </div>
- </dd>
-
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>Let <var>keyData</var> be the key data to be imported.</p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#concept-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a> are not present in
- <var>normalizedAlgorithm</var> then <a href="#concept-return-an-error">return
- an error</a> named <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the
- <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>algorithm</code> AlgorithmIdentifier field of
- <var>spki</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in Section 2.3.1 of <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha1WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha256WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha384WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha512WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
- <var>structure</var> as the <code>RSAPublicKey</code> structure
- specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA public key identified by
- <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>privateKeyAlgorithm</code>
- PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in Section 2.3.1 of <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha1WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha256WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha384WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>sha512WithRSAEncryption</code> OID defined in Section A.2.4 of
- <a href="#RFC3279">RFC 3279</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>rsaPrivateKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>privateKey</code> field of <var>privateKeyInfo</var>,
- <var>structure</var> as the <code>RSAPrivateKey</code> structure
- specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA private key identified by
- <var>rsaPrivateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not a
- case-sensitive string match to <code>"RSA"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not a case-sensitive string match to <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is not
- present:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"RS1"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"RS256"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"RS384"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"RS512"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.3.2 of <a href="#jwa">JSON Web
- Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA private key identified by interpreting <var>jwk</var>
- according to Section 6.3.2 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA public key identified by interpreting <var>jwk</var>
- according to Section 6.3.1 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a> dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSASSA-PKCS1-v1_5"</code>
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to the length, in bits, of the RSA public
- modulus.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
- representation of the RSA public exponent.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
- <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
- whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>Return <var>key</var>.</p>
- </li>
- </ol>
- </dd>
-
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>key</var> be the key to be exported.
- </p>
- </li>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code></dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>1.2.840.113549.1.1</code>
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to the ASN.1 type NULL.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> field to the result of
- DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
- in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
- represents the RSA public key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
- with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>version</var> field to 0.
- </p>
- </li>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to a
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>1.2.840.113549.1.1</code>
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to the ASN.1 type NULL.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to the result of DER-encoding
- an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
- RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- <div class="ednote"><div class="ednoteHeader">Editorial note</div>
- <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
- this field should be <em>BER</em> encoded in Section 5 (as a "for
- example"). However, to avoid requiring WebCrypto implementations
- support BER-encoding and BER-decoding, only <em>DER</em> encodings
- are produced or accepted.
- </div>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ul>
- <li>
- <p>Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.</p>
- </li>
- <li>
- <p>Set the <code>kty</code> attribute of <var>jwk</var> to the string
- <code>"RSA"</code>.</p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
- attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>hash</var> is <code>SHA-1</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>RS1</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-256</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>RS256</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-384</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>RS384</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-512</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>RS512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>RSA1_5</code>.</p>
- </li>
- <li>
- <p>
- Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
- according to the corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.1.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>"private"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Set the attributes named <code>d</code>, <code>p</code>,
- <code>q</code>, <code>dp</code>, <code>dq</code>, and
- <code>qi</code> of <var>jwk</var> according to the
- corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.2.
- </p>
- </li>
- <li>
- <p>
- If the underlying RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var> is represented by more than two primes, set
- the attribute named <code>oth</code> of <var>jwk</var>
- according to the corresponding definition in <a href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ul>
- </dd>
- <dt>Otherwise</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="rsa-pss" class="section">
- <h3>20.5. RSA-PSS</h3>
- <div id="rsa-pss-description" class="section">
- <h4>20.5.1. Description</h4>
+ </code></pre></div></div>
+ </div>
+ <div id="RsaHashedKeyAlgorithm-dictionary" class="section">
+ <h4>22.4. RsaHashedKeyAlgorithm dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</dfn> : <a href="#dfn-RsaKeyAlgorithm">RsaKeyAlgorithm</a> {
+<span class="comment">// The hash algorithm that is used with this key</span>
+<a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> <dfn id="dfn-RsaHashedKeyAlgorithm-hash">hash</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="RsaHashedImportParams-dictionary" class="section">
+ <h4>22.5. RsaHashedImportParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-RsaHashedImportParams">RsaHashedImportParams</dfn> {
+<span class="comment">// The hash algorithm to use</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-RsaHashedImportParams-hash">hash</dfn>;
+};
+ </code></pre></div></div>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div>
<p>
- The <code>"RSA-PSS"</code> algorithm identifier is used to perform signing
- and verification using the RSASSA-PSS algorithm specified in
- [<cite><a href="#RFC3447">RFC3447</a></cite>], using the mask generation
- formula MGF1.
+ Should this be folded into RsaHashedKeyGenParams and rely on the optional nature of the
+ dictionary fields?
</p>
</div>
- <div id="rsa-pss-registration" class="section">
- <h4>20.5.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"RSA-PSS"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>sign</td>
- <td><a href="#dfn-RsaPssParams">RsaPssParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>verify</td>
- <td><a href="#dfn-RsaPssParams">RsaPssParams</a></td>
- <td>boolean</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="RsaPssParams-dictionary" class="section">
- <h4>20.5.3. RsaPssParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-RsaPssParams">RsaPssParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The desired length of the random salt</span>
- [EnforceRange] unsigned long <dfn id="dfn-RsaPssParams-saltLength">saltLength</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="rsa-pss-operations" class="section">
- <h4>20.5.4. Operations</h4>
- <dl>
- <dt>Sign</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaPssParams">RsaPssParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaPssParams">RsaPssParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the signature generation operation defined in Section 8.1 of [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- as the signer's private key, <var>K</var>, and the <a href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
- the message to be signed, <var>M</var>, and using the hash function specified
- by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
- [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option, MGF1 (defined in Section B.2.1 of [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option and the <a href="#dfn-RsaPssParams-saltLength">saltLength</a> member of
- <var>normalizedAlgorithm</var> as the salt length option for the
- EMM-PSS-ENCODE operation.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>signature</var> be a new <code>ArrayBuffer</code> containing the
- signature, S, that results from performing the operation.
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Verify</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaPssParams">RsaPssParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaPssParams">RsaPssParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the signature verification operation defined in Section 8.1 of
- [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the
- [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> as the signer's RSA public key and the <a href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
- <var>M</var> and <a href="#concept-contents-of-arraybuffer">the contents of
- <var>signature</var></a> as <var>S</var> and using the hash function specified
- by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
- [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option, MGF1 (defined in Section B.2.1 of [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option and the <a href="#dfn-RsaPssParams-saltLength">saltLength</a> member of
- <var>normalizedAlgorithm</var> as the salt length option for the
- EMSA-PSS-VERIFY operation.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a boolean with value true if the
- result of the operation was "valid signature" and a boolean with value
- false otherwise.
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a> are not present
- in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an RSA key pair, as defined in [<cite><a href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> member of
- <var>normalizedAlgorithm</var> and RSA public exponent equal to the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSA-PSS"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
- of <var>algorithm</var> to equal the
- <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the <a href="#concept-usage-intersection">usage
- intersection</a> of <var>usages</var> and <code>[ "verify" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
- intersection</a> of <var>usages</var> and <code>[ "sign" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object,
- as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>Let <var>keyData</var> be the key data to be imported.</p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#concept-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a> are not present in
- <var>normalizedAlgorithm</var> then <a href="#concept-return-an-error">return
- an error</a> named <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the
- <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>algorithm</code> AlgorithmIdentifier field of
- <var>spki</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the
- <code>id-RSASSA-PSS</code> OID defined in
- <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>params</var> be the ASN.1 structure contained within
- the <code>parameters</code> field of the <code>algorithm</code>
- AlgorithmIdentifier field of <var>spki</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not defined, or is not an instance of
- the <code>RSASSA-PSS-params</code> ASN.1 type defined in
- <a href="#RFC3447">RFC3447</a>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
- within the <code>hashAlgorithm</code> field of <var>params</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- equivalent to the OID <code>id-mgf1</code> defined in <a href="#RFC3447">RFC 3447</a>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- an instance of the <code>HashAlgorithm</code> ASN.1 type that is
- identical in content to the <code>hashAlglorithm</code> field of
- <var>params</var>, <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
- <var>structure</var> as the <code>RSAPublicKey</code> structure
- specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA public key identified by
- <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>privateKeyAlgorithm</code>
- PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the <code>id-RSASSA-PSS</code> OID
- defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>params</var> be the ASN.1 structure contained within
- the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier
- field of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not defined, or is not an instance of
- the <code>RSASSA-PSS-params</code> ASN.1 type defined in
- <a href="#RFC3447">RFC3447</a>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
- within the <code>hashAlgorithm</code> field of <var>params</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- equivalent to the OID <code>id-mgf1</code> defined in <a href="#RFC3447">RFC 3447</a>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- an instance of the <code>HashAlgorithm</code> ASN.1 type that is
- identical in content to the <code>hashAlglorithm</code> field of
- <var>params</var>, <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>rsaPrivateKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>privateKey</code> field of <var>privateKeyInfo</var>,
- <var>structure</var> as the <code>RSAPrivateKey</code> structure
- specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA private key identified by
- <var>rsaPrivateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not a
- case-sensitive string match to <code>"RSA"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not a case-sensitive string match to <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is not
- present:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"PS1"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"PS256"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"PS384"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string
- <code>"PS512"</code>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.3.2 of <a href="#jwa">JSON Web
- Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA private key identified by interpreting <var>jwk</var>
- according to Section 6.3.2 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA public key identified by interpreting <var>jwk</var>
- according to Section 6.3.1 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
+ </div>
+ <div id="rsassa-pkcs1-operations" class="section">
+ <h4>22.6. Operations</h4>
+ <dl>
+ <dt>Sign</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the signature generation operation defined in Section 8.2 of [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ as the signer's private key and the <a href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
+ <var>M</var> and using the hash function specified in the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>signature</var> be the value <var>S</var> that results from
+ performing the operation.
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Verify</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the signature verification operation defined in Section 8.2 of
+ [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the
+ [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> as the signer's RSA public key and the <a href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
+ <var>M</var> and the <a href="#concept-contents-of-arraybuffer">contents of
+ <var>signature</var></a> as <var>S</var> and using the hash function specified
+ in the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
+ [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a boolean with value true if the
+ result of the operations was "valid signature" and a boolean with value
+ false otherwise.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an RSA key pair, as defined in [<cite><a href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> attribute of
+ <var>normalizedAlgorithm</var> and RSA public exponent equal to the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> attribute of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If generation of the key pair fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSASSA-PKCS1-v1_5"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
+ attribute of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
+ attribute of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
+ of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the <a href="#concept-usage-intersection">usage
+ intersection</a> of <var>usages</var> and <code>[ "verify" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
+ intersection</a> of <var>usages</var> and <code>[ "sign" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to be <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to be <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object, as
+ defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div>
+ <p>
+ TODO: Specify the mapping between key.algorithm.hash and the appropriate Hash
+ functions (and back to OID).
+ </p>
+ </div>
+ </dd>
+
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>Let <var>keyData</var> be the key data to be imported.</p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the
+ <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>algorithm</code> AlgorithmIdentifier field of
+ <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in Section 2.3.1 of <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha1WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha256WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha384WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha512WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
+ <var>structure</var> as the <code>RSAPublicKey</code> structure
+ specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA public key identified by
+ <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>privateKeyAlgorithm</code>
+ PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in Section 2.3.1 of <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha1WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha256WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha384WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>sha512WithRSAEncryption</code> OID defined in Section A.2.4 of
+ <a href="#RFC3279">RFC 3279</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>rsaPrivateKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>privateKey</code> field of <var>privateKeyInfo</var>,
+ <var>structure</var> as the <code>RSAPrivateKey</code> structure
+ specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA private key identified by
+ <var>rsaPrivateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not a
+ case-sensitive string match to <code>"RSA"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not a case-sensitive string match to <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is not
+ present:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"RS1"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"RS256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"RS384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"RS512"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.3.2 of <a href="#jwa">JSON Web
+ Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA private key identified by interpreting <var>jwk</var>
+ according to Section 6.3.2 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA public key identified by interpreting <var>jwk</var>
+ according to Section 6.3.1 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a> dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSASSA-PKCS1-v1_5"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to the length, in bits, of the RSA public
+ modulus.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
+ representation of the RSA public exponent.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
+ <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>Return <var>key</var>.</p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>key</var> be the key to be exported.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code></dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>1.2.840.113549.1.1</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to the ASN.1 type NULL.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> field to the result of
+ DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
+ in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
+ represents the RSA public key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
+ with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>version</var> field to 0.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to a
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>1.2.840.113549.1.1</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to the ASN.1 type NULL.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to the result of DER-encoding
+ an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
+ RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div>
+ <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
+ this field should be <em>BER</em> encoded in Section 5 (as a "for
+ example"). However, to avoid requiring WebCrypto implementations
+ support BER-encoding and BER-decoding, only <em>DER</em> encodings
+ are produced or accepted.
+ </div>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ul>
+ <li>
+ <p>Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.</p>
+ </li>
+ <li>
+ <p>Set the <code>kty</code> attribute of <var>jwk</var> to the string
+ <code>"RSA"</code>.</p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
+ attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>hash</var> is <code>SHA-1</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>RS1</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-256</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>RS256</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-384</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>RS384</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-512</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>RS512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>RSA1_5</code>.</p>
+ </li>
+ <li>
+ <p>
+ Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
+ according to the corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.1.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is <code>"private"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Set the attributes named <code>d</code>, <code>p</code>,
+ <code>q</code>, <code>dp</code>, <code>dq</code>, and
+ <code>qi</code> of <var>jwk</var> according to the
+ corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.2.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var> is represented by more than two primes, set
+ the attribute named <code>oth</code> of <var>jwk</var>
+ according to the corresponding definition in <a href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ul>
+ </dd>
+ <dt>Otherwise</dt>
+ <dd>
+ <p>
<a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a> dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSA-PSS"</code>
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to the length, in bits, of the RSA public
- modulus.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
- representation of the RSA public exponent.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
- <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
- whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>
- </p>
- </li>
- <li>
- <p>Return <var>key</var>.</p>
- </li>
- </ol>
- </dd>
-
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>key</var> be the key to be exported.
- </p>
- </li>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code></dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-RSASSA-PSS</code> defined in
- <a href="#RFC3447">RFC 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>RSASSA-PSS-params</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>hashAlgorithm</var> field to an instance of
- the <code>HashAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-1</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha1</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-256</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha256</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-384</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha384</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-512</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha512</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <var>maskGenAlgorithm</var> field to an instance
- of the <code>MaskGenAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
- 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>HashAlgorithm</code> ASN.1 type that is
- identical to the <var>hashAlgorithm</var> field.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>saltLength</var> field to the length in
- octets of the digest algorithm identified by the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
- of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> field to the result of
- DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
- in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
- represents the RSA public key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
- with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>version</var> field to 0.
- </p>
- </li>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to an
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-RSASSA-PSS</code> defined in
- <a href="#RFC3447">RFC 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>RSASSA-PSS-params</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>hashAlgorithm</var> field to an instance of
- the <code>HashAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-1</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha1</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-256</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha256</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-384</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha384</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-512</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha512</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <var>maskGenAlgorithm</var> field to an instance
- of the <code>MaskGenAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
- 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>HashAlgorithm</code> ASN.1 type that is
- identical to the <var>hashAlgorithm</var> field.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>saltLength</var> field to the length in
- octets of the digest algorithm identified by the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
- of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to the result of DER-encoding
- an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
- RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- <div class="ednote"><div class="ednoteHeader">Editorial note</div>
- <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
- this field should be <em>BER</em> encoded in Section 5 (as a "for
- example"). However, to avoid requiring WebCrypto implementations
- support BER-encoding and BER-decoding, only <em>DER</em> encodings
- are produced or accepted.
- </div>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ul>
- <li>
- <p>Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a> dictionary.</p>
- </li>
- <li>
- <p>Set the <code>kty</code> attribute of <var>jwk</var> to the string
- <code>"RSA"</code>.</p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>hash</var> is <code>SHA-1</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>PS1</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-256</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>PS256</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-384</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>PS384</code>.
- </p>
- </dd>
- <dt>If <var>hash</var> is <code>SHA-512</code>:</dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>PS512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
- according to the corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.1.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is <code>"private"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Set the attributes named <code>d</code>, <code>p</code>,
- <code>q</code>, <code>dp</code>, <code>dq</code>, and
- <code>qi</code> of <var>jwk</var> according to the
- corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.2.
- </p>
- </li>
- <li>
- <p>
- If the underlying RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var> is represented by more than two primes, set
- the attribute named <code>oth</code> of <var>jwk</var>
- according to the corresponding definition in <a href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ul>
- </dd>
- <dt>Otherwise</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="rsa-oaep" class="section">
- <h3>20.6. RSA-OAEP</h3>
- <div id="rsa-oaep-description" class="section">
- <h4>20.6.1. Description</h4>
- <p>
- The <code>"RSA-OAEP"</code> algorithm identifier is used to perform encryption
- and decryption ordering to the RSAES-OAEP algorithm specified in
- [<cite><a href="#RFC3447">RFC3447</a></cite>], using the mask
- generation function MGF1.
- </p>
- </div>
- <div id="rsa-oaep-registration" class="section">
- <h4>20.6.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"RSA-OAEP"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>encrypt</td>
- <td><a href="#dfn-RsaOaepParams">RsaOaepParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>decrypt</td>
- <td><a href="#dfn-RsaOaepParams">RsaOaepParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- </tbody>
- </table>
- </div>
-
- <div id="rsa-oaep-params" class="section">
- <h4>20.6.3. RsaOaepParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-RsaOaepParams">RsaOaepParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The optional label/application data to associate with the message</span>
- CryptoOperationData? <dfn id="dfn-RsaOaepParams-label">label</dfn>;
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="rsa-pss" class="section">
+ <h3>23. RSA-PSS</h3>
+ <div id="rsa-pss-description" class="section">
+ <h4>23.1. Description</h4>
+ <p>
+ The <code>"RSA-PSS"</code> algorithm identifier is used to perform signing
+ and verification using the RSASSA-PSS algorithm specified in
+ [<cite><a href="#RFC3447">RFC3447</a></cite>], using the mask generation
+ formula MGF1.
+ </p>
+ </div>
+ <div id="rsa-pss-registration" class="section">
+ <h4>23.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"RSA-PSS"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sign</td>
+ <td><a href="#dfn-RsaPssParams">RsaPssParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>verify</td>
+ <td><a href="#dfn-RsaPssParams">RsaPssParams</a></td>
+ <td>boolean</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="RsaPssParams-dictionary" class="section">
+ <h4>23.3. RsaPssParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-RsaPssParams">RsaPssParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The desired length of the random salt</span>
+[EnforceRange] unsigned long <dfn id="dfn-RsaPssParams-saltLength">saltLength</dfn>;
};
- </code></pre></div></div>
- </div>
- <div id="rsa-oaep-operations" class="section">
- <h4>20.6.4. Operations</h4>
- <dl>
- <dt>Encrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of <var>key</var>
- is not <code>"public"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaOaepParams">RsaOaepParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaOaepParams">RsaOaepParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the encryption operation defined in Section 7.1 of [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by <var>key</var>
- as the recipient's RSA public key, the <a href="#concept-contents-of-arraybuffer">contents of <var>plaintext</var></a>
- as the message to be encrypted, <var>M</var> and the <a href="#concept-contents-of-arraybuffer">contents of</a> <a href="#dfn-RsaOaepParams-label">label</a> member of
- <var>normalizedAlgorithm</var> as the label, <var>L</var>, and with the hash
- function specified by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option and MGF1 (defined in Section B.2.1 of
- [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ciphertext</var> be a new <code>ArrayBuffer</code>
- containing the value <var>C</var> that results from performing the
- operation.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Decrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of <var>key</var>
- is not <code>"private"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaOaepParams">RsaOaepParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaOaepParams">RsaOaepParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the decryption operation defined in Section 7.1 of [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by <var>key</var>
- as the recipient's RSA private key, the <a href="#concept-contents-of-arraybuffer">contents of <var>ciphertext</var></a>
- as the ciphertext to be decrypted, C, and the <a href="#concept-contents-of-arraybuffer">contents of</a> the <a href="#dfn-RsaOaepParams-label">label</a> member of
- <var>normalizedAlgorithm</var> as the label, <var>L</var>, and with the hash
- function specified by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> as the Hash option and MGF1 (defined in Section B.2.1 of
- [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>plaintext</var> be a new <code>ArrayBuffer</code>
- containing the value <var>M</var> that results from performing the
- operation.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a> are not present
- in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- <code>"encrypt"</code>, <code>"decrypt</code>,
- <code>wrapKey</code> or <code>unwrapKey</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an RSA key pair, as defined in [<cite><a href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> member of
- <var>normalizedAlgorithm</var> and RSA public exponent equal to the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSA-OAEP"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the
- <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
- of <var>algorithm</var> to equal the
- <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot of
- <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the
- <a href="#concept-usage-intersection">usage intersection</a> of
- <var>usages</var> and <code>[ "encrypt", "wrapKey" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot of
- <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be the
- <a href="#concept-usage-intersection">usage intersection</a> of
- <var>usages</var> and <code>[ "decrypt", "unwrapKey" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to be <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to be <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object, as
- defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>Let <var>keyData</var> be the key data to be imported.</p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#concept-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a> are not present in
- <var>normalizedAlgorithm</var> then <a href="#concept-return-an-error">return
- an error</a> named <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the
- <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>algorithm</code> AlgorithmIdentifier field of
- <var>spki</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the <code>id-RSAES-OAEP</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>params</var> be the ASN.1 structure contained within
- the <code>parameters</code> field of the <code>algorithm</code>
- AlgorithmIdentifier field of <var>spki</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not defined, or is not an instance of
- the <code>RSAES-OAEP-params</code> ASN.1 type defined in
- <a href="#RFC3447">RFC3447</a>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
- within the <code>hashAlgorithm</code> field of <var>params</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- equivalent to the OID <code>id-mgf1</code> defined in <a href="#RFC3447">RFC 3447</a>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- an instance of the <code>HashAlgorithm</code> ASN.1 type that is
- identical in content to the <code>hashAlglorithm</code> field of
- <var>params</var>, <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
- <var>structure</var> as the <code>RSAPublicKey</code> structure
- specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA public key identified by
- <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <p>
- Let <var>alg</var> be the <code>algorithm</code> object identifier
- field of the <code>privateKeyAlgorithm</code>
- PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Let <var>hash</var> be undefined.
- </p>
- </dd>
- <dt>
- If <var>alg</var> is equivalent to the <code>id-RSAES-OAEP</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>params</var> be the ASN.1 structure contained within
- the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier
- field of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not defined, or is not an instance of
- the <code>RSAES-OAEP-params</code> ASN.1 type defined in <a href="#RFC3447">RFC3447</a>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
- within the <code>hashAlgorithm</code> field of
- <var>params</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
- OID defined in <a href="#RFC3447">RFC 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-1</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the
- <code>id-sha256</code> OID defined in <a href="#RFC3447">RFC
- 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-256</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the
- <code>id-sha384</code> OID defined in <a href="#RFC3447">RFC
- 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-384</code>.
- </p>
- </dd>
- <dt>
- If the <code>algorithm</code> object identifier field of
- <var>hashAlg</var> is equivalent to the
- <code>id-sha512</code> OID defined in <a href="#RFC3447">RFC
- 3447</a>:
- </dt>
- <dd>
- <p>
- Set <var>hash</var> to the string <code>SHA-512</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- equivalent to the OID <code>id-mgf1</code> defined in <a href="#RFC3447">RFC 3447</a>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>maskGenAlgorithm</code> field of <var>params</var> is not
- an instance of the <code>HashAlgorithm</code> ASN.1 type that is
- identical in content to the <code>hashAlglorithm</code> field of
- <var>params</var>, <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>rsaPrivateKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the
- <code>privateKey</code> field of <var>privateKeyInfo</var>,
- <var>structure</var> as the <code>RSAPrivateKey</code> structure
- specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
- <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the RSA private key identified by
- <var>rsaPrivateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not a
- case-sensitive string match to <code>"RSA"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not a case-sensitive string match to <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a string whose initial value is undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>alg</code> field of <var>jwk</var> is not present:</dt>
- <dd>Let <var>hash</var> be undefined.</dd>
- <dt>
- If the <code>alg</code> field of <var>jwk</var> is equal to
- <code>RSA-OAEP</code>:
- </dt>
- <dd>Let <var>hash</var> be the string <code>SHA-1</code>.</dd>
- <dt>
- If the <code>alg</code> field of <var>jwk</var> is equal to
- <code>RSA-OAEP-256</code>:
- </dt>
- <dd>Let <var>hash</var> be the string <code>SHA-256</code>.</dd>
- <dt>
- If the <code>alg</code> field of <var>jwk</var> is equal to
- <code>RSA-OAEP-384</code>:
- </dt>
- <dd>Let <var>hash</var> be the string <code>SHA-384</code>.</dd>
- <dt>
- If the <code>alg</code> field of <var>jwk</var> is equal to
- <code>RSA-OAEP-512</code>:
- </dt>
- <dd>Let <var>hash</var> be the string <code>SHA-512</code>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">return an error</a> named
+ </code></pre></div></div>
+ </div>
+ <div id="rsa-pss-operations" class="section">
+ <h4>23.4. Operations</h4>
+ <dl>
+ <dt>Sign</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the signature generation operation defined in Section 8.1 of [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ as the signer's private key, <var>K</var>, and the <a href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
+ the message to be signed, <var>M</var>, and using the hash function specified
+ by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
+ [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option, MGF1 (defined in Section B.2.1 of [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option and the <a href="#dfn-RsaPssParams-saltLength">saltLength</a> member of
+ <var>normalizedAlgorithm</var> as the salt length option for the
+ EMM-PSS-ENCODE operation.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>signature</var> be a new <code>ArrayBuffer</code> containing the
+ signature, S, that results from performing the operation.
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Verify</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the signature verification operation defined in Section 8.1 of
+ [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by the
+ [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> as the signer's RSA public key and the <a href="#concept-contents-of-arraybuffer">contents of <var>message</var></a> as
+ <var>M</var> and <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>signature</var></a> as <var>S</var> and using the hash function specified
+ by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of the
+ [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option, MGF1 (defined in Section B.2.1 of [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option and the <a href="#dfn-RsaPssParams-saltLength">saltLength</a> member of
+ <var>normalizedAlgorithm</var> as the salt length option for the
+ EMSA-PSS-VERIFY operation.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a boolean with value true if the
+ result of the operation was "valid signature" and a boolean with value
+ false otherwise.
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an RSA key pair, as defined in [<cite><a href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> member of
+ <var>normalizedAlgorithm</var> and RSA public exponent equal to the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSA-PSS"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
+ of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the <a href="#concept-usage-intersection">usage
+ intersection</a> of <var>usages</var> and <code>[ "verify" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
+ intersection</a> of <var>usages</var> and <code>[ "sign" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object,
+ as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>Let <var>keyData</var> be the key data to be imported.</p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the
+ <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>algorithm</code> AlgorithmIdentifier field of
+ <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the
+ <code>id-RSASSA-PSS</code> OID defined in
+ <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>params</var> be the ASN.1 structure contained within
+ the <code>parameters</code> field of the <code>algorithm</code>
+ AlgorithmIdentifier field of <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not defined, or is not an instance of
+ the <code>RSASSA-PSS-params</code> ASN.1 type defined in
+ <a href="#RFC3447">RFC3447</a>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
+ within the <code>hashAlgorithm</code> field of <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ equivalent to the OID <code>id-mgf1</code> defined in <a href="#RFC3447">RFC 3447</a>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ an instance of the <code>HashAlgorithm</code> ASN.1 type that is
+ identical in content to the <code>hashAlglorithm</code> field of
+ <var>params</var>, <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.3.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA private key identified by interpreting <var>jwk</var>
- according to Section 6.3.2 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"private"</code>
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- RSA public key identified by interpreting <var>jwk</var>
- according to Section 6.3.1 of <a href="#jwa"> JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"public"</code>
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
+ <var>structure</var> as the <code>RSAPublicKey</code> structure
+ specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA public key identified by
+ <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>privateKeyAlgorithm</code>
+ PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the <code>id-RSASSA-PSS</code> OID
+ defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>params</var> be the ASN.1 structure contained within
+ the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier
+ field of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not defined, or is not an instance of
+ the <code>RSASSA-PSS-params</code> ASN.1 type defined in
+ <a href="#RFC3447">RFC3447</a>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
+ within the <code>hashAlgorithm</code> field of <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ equivalent to the OID <code>id-mgf1</code> defined in <a href="#RFC3447">RFC 3447</a>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ an instance of the <code>HashAlgorithm</code> ASN.1 type that is
+ identical in content to the <code>hashAlglorithm</code> field of
+ <var>params</var>, <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>rsaPrivateKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>privateKey</code> field of <var>privateKeyInfo</var>,
+ <var>structure</var> as the <code>RSAPrivateKey</code> structure
+ specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA private key identified by
+ <var>rsaPrivateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not a
+ case-sensitive string match to <code>"RSA"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not a case-sensitive string match to <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is not
+ present:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"PS1"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"PS256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"PS384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string
+ <code>"PS512"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.3.2 of <a href="#jwa">JSON Web
+ Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA private key identified by interpreting <var>jwk</var>
+ according to Section 6.3.2 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA public key identified by interpreting <var>jwk</var>
+ according to Section 6.3.1 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a> dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSA-PSS"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to the length, in bits, of the RSA public
+ modulus.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
+ representation of the RSA public exponent.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
+ <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>
+ </p>
+ </li>
+ <li>
+ <p>Return <var>key</var>.</p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>key</var> be the key to be exported.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code></dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-RSASSA-PSS</code> defined in
+ <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>RSASSA-PSS-params</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>hashAlgorithm</var> field to an instance of
+ the <code>HashAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-1</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha1</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-256</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha256</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-384</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha384</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-512</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha512</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <var>maskGenAlgorithm</var> field to an instance
+ of the <code>MaskGenAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
+ 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>HashAlgorithm</code> ASN.1 type that is
+ identical to the <var>hashAlgorithm</var> field.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>saltLength</var> field to the length in
+ octets of the digest algorithm identified by the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
+ of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> field to the result of
+ DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
+ in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
+ represents the RSA public key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
+ with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>version</var> field to 0.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to an
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-RSASSA-PSS</code> defined in
+ <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>RSASSA-PSS-params</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>hashAlgorithm</var> field to an instance of
+ the <code>HashAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-1</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha1</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-256</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha256</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-384</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha384</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-512</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha512</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <var>maskGenAlgorithm</var> field to an instance
+ of the <code>MaskGenAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
+ 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>HashAlgorithm</code> ASN.1 type that is
+ identical to the <var>hashAlgorithm</var> field.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>saltLength</var> field to the length in
+ octets of the digest algorithm identified by the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
+ of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to the result of DER-encoding
+ an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
+ RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div>
+ <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
+ this field should be <em>BER</em> encoded in Section 5 (as a "for
+ example"). However, to avoid requiring WebCrypto implementations
+ support BER-encoding and BER-decoding, only <em>DER</em> encodings
+ are produced or accepted.
+ </div>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ul>
+ <li>
+ <p>Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a> dictionary.</p>
+ </li>
+ <li>
+ <p>Set the <code>kty</code> attribute of <var>jwk</var> to the string
+ <code>"RSA"</code>.</p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>hash</var> is <code>SHA-1</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>PS1</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-256</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>PS256</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-384</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>PS384</code>.
+ </p>
+ </dd>
+ <dt>If <var>hash</var> is <code>SHA-512</code>:</dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>PS512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
+ according to the corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.1.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is <code>"private"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Set the attributes named <code>d</code>, <code>p</code>,
+ <code>q</code>, <code>dp</code>, <code>dq</code>, and
+ <code>qi</code> of <var>jwk</var> according to the
+ corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.2.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var> is represented by more than two primes, set
+ the attribute named <code>oth</code> of <var>jwk</var>
+ according to the corresponding definition in <a href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ul>
+ </dd>
+ <dt>Otherwise</dt>
+ <dd>
+ <p>
<a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"RSA-OAEP"</code>
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
- attribute of <var>algorithm</var> to the length, in bits, of the RSA public
- modulus.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
- attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
- representation of the RSA public exponent.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
- <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
- whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> to <var>algorithm</var>
- </p>
- </li>
- <li>
- <p>Return <var>key</var>.</p>
- </li>
- </ol>
- </dd>
-
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>key</var> be the key to be exported.
- </p>
- </li>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code></dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-RSAES-OAEP</code> defined in
- <a href="#RFC3447">RFC 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>RSAES-OAEP-params</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>hashAlgorithm</var> field to an instance of
- the <code>HashAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-1</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha1</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-256</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha256</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-384</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha384</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-512</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha512</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <var>maskGenAlgorithm</var> field to an instance
- of the <code>MaskGenAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
- 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>HashAlgorithm</code> ASN.1 type that is
- identical to the <var>hashAlgorithm</var> field.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> field to the result of
- DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
- in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
- represents the RSA public key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
- with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>version</var> field to 0.
- </p>
- </li>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to an
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-RSAES-OAEP</code> defined in
- <a href="#RFC3447">RFC 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>RSAES-OAEP-params</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>hashAlgorithm</var> field to an instance of
- the <code>HashAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-1</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha1</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-256</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha256</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-384</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha384</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a>
- attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>SHA-512</code>:
- </dt>
- <dd>
- <p>
- Set the <var>algorithm</var> object identifier to the
- OID <code>id-sha512</code> defined in <a href="#RFC3447">RFC 3447</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <var>maskGenAlgorithm</var> field to an instance
- of the <code>MaskGenAlgorithm</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the OID
- <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
- 3447</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>params</var> field to an instance of the
- <code>HashAlgorithm</code> ASN.1 type that is
- identical to the <var>hashAlgorithm</var> field.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to the result of DER-encoding
- an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
- RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>
- </p>
- <div class="ednote"><div class="ednoteHeader">Editorial note</div>
- <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
- this field should be <em>BER</em> encoded in Section 5 (as a "for
- example"). However, to avoid requiring WebCrypto implementations
- support BER-encoding and BER-decoding, only <em>DER</em> encodings
- are produced or accepted.
- </div>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ul>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the string
- <code>"RSA"</code>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>SHA-1</code>:
- </dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>"RSA-OAEP"</code>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>SHA-256</code>:
- </dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>"RSA-OAEP-256"</code>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>SHA-384</code>:
- </dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>"RSA-OAEP-384"</code>.
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>SHA-512</code>:
- </dt>
- <dd>
- <p>
- Set the <code>alg</code> attribute of <var>jwk</var> to the string
- <code>"RSA-OAEP-512"</code>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
- according to the corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.1.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>"private"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Set the attributes named <code>d</code>, <code>p</code>,
- <code>q</code>, <code>dp</code>, <code>dq</code>, and
- <code>qi</code> of <var>jwk</var> according to the
- corresponding definitions in <a href="#jwa">JSON Web
- Algorithms</a>, Section 6.3.2.
- </p>
- </li>
- <li>
- <p>
- If the underlying RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var> is represented by more than two primes, set
- the attribute named <code>oth</code> of <var>jwk</var>
- according to the corresponding definition in <a href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ul>
- </dd>
- <dt>Otherwise</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="ecdsa" class="section">
- <h3>20.7. ECDSA</h3>
- <div id="ecdsa-description" class="section">
- <h4>20.7.1. Description</h4>
- <p>
- The <code>"ECDSA"</code> algorithm identifier is used to perform signing
- and verification using the ECDSA algorithm specified in
- [<cite><a href="#X9.62">X9.62</a></cite>].
- </p>
- </div>
- <div id="ecdsa-registration" class="section">
- <h4>20.7.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"ECDSA"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>sign</td>
- <td><a href="#dfn-EcdsaParams">EcdsaParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>verify</td>
- <td><a href="#dfn-EcdsaParams">EcdsaParams</a></td>
- <td>boolean</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-EcKeyGenParams">EcKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
-
- </tbody>
- </table>
- </div>
- <div id="EcdsaParams-dictionary" class="section">
- <h4>20.7.3. EcdsaParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="rsa-oaep" class="section">
+ <h3>24. RSA-OAEP</h3>
+ <div id="rsa-oaep-description" class="section">
+ <h4>24.1. Description</h4>
+ <p>
+ The <code>"RSA-OAEP"</code> algorithm identifier is used to perform encryption
+ and decryption ordering to the RSAES-OAEP algorithm specified in
+ [<cite><a href="#RFC3447">RFC3447</a></cite>], using the mask
+ generation function MGF1.
+ </p>
+ </div>
+ <div id="rsa-oaep-registration" class="section">
+ <h4>24.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"RSA-OAEP"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>encrypt</td>
+ <td><a href="#dfn-RsaOaepParams">RsaOaepParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>decrypt</td>
+ <td><a href="#dfn-RsaOaepParams">RsaOaepParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-RsaHashedImportParams">RsaHashedImportParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <div id="rsa-oaep-params" class="section">
+ <h4>24.3. RsaOaepParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-RsaOaepParams">RsaOaepParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The optional label/application data to associate with the message</span>
+CryptoOperationData? <dfn id="dfn-RsaOaepParams-label">label</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="rsa-oaep-operations" class="section">
+ <h4>24.4. Operations</h4>
+ <dl>
+ <dt>Encrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of <var>key</var>
+ is not <code>"public"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the encryption operation defined in Section 7.1 of [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by <var>key</var>
+ as the recipient's RSA public key, the <a href="#concept-contents-of-arraybuffer">contents of <var>plaintext</var></a>
+ as the message to be encrypted, <var>M</var> and the <a href="#concept-contents-of-arraybuffer">contents of</a> <a href="#dfn-RsaOaepParams-label">label</a> member of
+ <var>normalizedAlgorithm</var> as the label, <var>L</var>, and with the hash
+ function specified by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option and MGF1 (defined in Section B.2.1 of
+ [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ciphertext</var> be a new <code>ArrayBuffer</code>
+ containing the value <var>C</var> that results from performing the
+ operation.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Decrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of <var>key</var>
+ is not <code>"private"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the decryption operation defined in Section 7.1 of [<cite><a href="#RFC3447">RFC3447</a></cite>] with the key represented by <var>key</var>
+ as the recipient's RSA private key, the <a href="#concept-contents-of-arraybuffer">contents of <var>ciphertext</var></a>
+ as the ciphertext to be decrypted, C, and the <a href="#concept-contents-of-arraybuffer">contents of</a> the <a href="#dfn-RsaOaepParams-label">label</a> member of
+ <var>normalizedAlgorithm</var> as the label, <var>L</var>, and with the hash
+ function specified by the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> as the Hash option and MGF1 (defined in Section B.2.1 of
+ [<cite><a href="#RFC3447">RFC3447</a></cite>]) as the MGF option.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>plaintext</var> be a new <code>ArrayBuffer</code>
+ containing the value <var>M</var> that results from performing the
+ operation.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ <code>"encrypt"</code>, <code>"decrypt</code>,
+ <code>wrapKey</code> or <code>unwrapKey</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an RSA key pair, as defined in [<cite><a href="#RFC3447">RFC3447</a></cite>], with RSA modulus length equal to the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a> member of
+ <var>normalizedAlgorithm</var> and RSA public exponent equal to the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSA-OAEP"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-modulusLength">modulusLength</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the
+ <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaKeyGenParams-publicExponent">publicExponent</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute
+ of <var>algorithm</var> to equal the
+ <a href="#dfn-RsaHashedKeyGenParams">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot of
+ <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the
+ <a href="#concept-usage-intersection">usage intersection</a> of
+ <var>usages</var> and <code>[ "encrypt", "wrapKey" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot of
+ <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be the
+ <a href="#concept-usage-intersection">usage intersection</a> of
+ <var>usages</var> and <code>[ "decrypt", "unwrapKey" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to be <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to be <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object, as
+ defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>Let <var>keyData</var> be the key data to be imported.</p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the
+ <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>algorithm</code> AlgorithmIdentifier field of
+ <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the <code>id-RSAES-OAEP</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>params</var> be the ASN.1 structure contained within
+ the <code>parameters</code> field of the <code>algorithm</code>
+ AlgorithmIdentifier field of <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not defined, or is not an instance of
+ the <code>RSAES-OAEP-params</code> ASN.1 type defined in
+ <a href="#RFC3447">RFC3447</a>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
+ within the <code>hashAlgorithm</code> field of <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha256</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha384</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha512</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ equivalent to the OID <code>id-mgf1</code> defined in <a href="#RFC3447">RFC 3447</a>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ an instance of the <code>HashAlgorithm</code> ASN.1 type that is
+ identical in content to the <code>hashAlglorithm</code> field of
+ <var>params</var>, <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>subjectPublicKeyInfo</code> field of <var>spki</var>,
+ <var>structure</var> as the <code>RSAPublicKey</code> structure
+ specified in Section A.1.1 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA public key identified by
+ <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>alg</var> be the <code>algorithm</code> object identifier
+ field of the <code>privateKeyAlgorithm</code>
+ PrivateKeyAlgorithmIdentifier field of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>alg</var> is equivalent to the <code>rsaEncryption</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Let <var>hash</var> be undefined.
+ </p>
+ </dd>
+ <dt>
+ If <var>alg</var> is equivalent to the <code>id-RSAES-OAEP</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>params</var> be the ASN.1 structure contained within
+ the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier
+ field of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not defined, or is not an instance of
+ the <code>RSAES-OAEP-params</code> ASN.1 type defined in <a href="#RFC3447">RFC3447</a>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlg</var> be the AlgorithmIdentifier ASN.1 type
+ within the <code>hashAlgorithm</code> field of
+ <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the <code>id-sha1</code>
+ OID defined in <a href="#RFC3447">RFC 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-1</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the
+ <code>id-sha256</code> OID defined in <a href="#RFC3447">RFC
+ 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-256</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the
+ <code>id-sha384</code> OID defined in <a href="#RFC3447">RFC
+ 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-384</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <code>algorithm</code> object identifier field of
+ <var>hashAlg</var> is equivalent to the
+ <code>id-sha512</code> OID defined in <a href="#RFC3447">RFC
+ 3447</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>hash</var> to the string <code>SHA-512</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ equivalent to the OID <code>id-mgf1</code> defined in <a href="#RFC3447">RFC 3447</a>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>maskGenAlgorithm</code> field of <var>params</var> is not
+ an instance of the <code>HashAlgorithm</code> ASN.1 type that is
+ identical in content to the <code>hashAlglorithm</code> field of
+ <var>params</var>, <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set <var>hash</var> to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>rsaPrivateKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the
+ <code>privateKey</code> field of <var>privateKeyInfo</var>,
+ <var>structure</var> as the <code>RSAPrivateKey</code> structure
+ specified in Section A.1.2 of <a href="#RFC3447">RFC 3447</a>, and
+ <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the RSA private key identified by
+ <var>rsaPrivateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not a
+ case-sensitive string match to <code>"RSA"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not a case-sensitive string match to <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a string whose initial value is undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>alg</code> field of <var>jwk</var> is not present:</dt>
+ <dd>Let <var>hash</var> be undefined.</dd>
+ <dt>
+ If the <code>alg</code> field of <var>jwk</var> is equal to
+ <code>RSA-OAEP</code>:
+ </dt>
+ <dd>Let <var>hash</var> be the string <code>SHA-1</code>.</dd>
+ <dt>
+ If the <code>alg</code> field of <var>jwk</var> is equal to
+ <code>RSA-OAEP-256</code>:
+ </dt>
+ <dd>Let <var>hash</var> be the string <code>SHA-256</code>.</dd>
+ <dt>
+ If the <code>alg</code> field of <var>jwk</var> is equal to
+ <code>RSA-OAEP-384</code>:
+ </dt>
+ <dd>Let <var>hash</var> be the string <code>SHA-384</code>.</dd>
+ <dt>
+ If the <code>alg</code> field of <var>jwk</var> is equal to
+ <code>RSA-OAEP-512</code>:
+ </dt>
+ <dd>Let <var>hash</var> be the string <code>SHA-512</code>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>hash</var> is defined, and is not equal to the <a href="#dfn-AlgorithmIdentifier-name">name</a> member of the <a href="#dfn-RsaHashedImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"d"</code> field of <var>jwk</var> is present:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.3.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA private key identified by interpreting <var>jwk</var>
+ according to Section 6.3.2 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.3.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ RSA public key identified by interpreting <var>jwk</var>
+ according to Section 6.3.1 of <a href="#jwa"> JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"RSA-OAEP"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-modulusLength">modulusLength</a>
+ attribute of <var>algorithm</var> to the length, in bits, of the RSA public
+ modulus.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaKeyAlgorithm-publicExponent">publicExponent</a>
+ attribute of <var>algorithm</var> to the <a href="#dfn-BigInteger">BigInteger</a>
+ representation of the RSA public exponent.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-RsaHashedKeyAlgorithm-hash">hash</a> attribute of
+ <var>algorithm</var> to a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ whose <a href="#dfn-KeyAlgorithm-name">name</a> attribute is <var>hash</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> to <var>algorithm</var>
+ </p>
+ </li>
+ <li>
+ <p>Return <var>key</var>.</p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>key</var> be the key to be exported.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code></dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a href="#dfn-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-RSAES-OAEP</code> defined in
+ <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>RSAES-OAEP-params</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>hashAlgorithm</var> field to an instance of
+ the <code>HashAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-1</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha1</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-256</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha256</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-384</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha384</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-512</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha512</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <var>maskGenAlgorithm</var> field to an instance
+ of the <code>MaskGenAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
+ 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>HashAlgorithm</code> ASN.1 type that is
+ identical to the <var>hashAlgorithm</var> field.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> field to the result of
+ DER-encoding an <code>RSAPublicKey</code> ASN.1 type, as defined
+ in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.1, that
+ represents the RSA public key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a href="#dfn-encode-a-privateKeyInfo"> encoding a privateKeyInfo</a>
+ with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>version</var> field to 0.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to an
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-RSAES-OAEP</code> defined in
+ <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>RSAES-OAEP-params</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>hashAlgorithm</var> field to an instance of
+ the <code>HashAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-1</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha1</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-256</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha256</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-384</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha384</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a>
+ attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>SHA-512</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <var>algorithm</var> object identifier to the
+ OID <code>id-sha512</code> defined in <a href="#RFC3447">RFC 3447</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <var>maskGenAlgorithm</var> field to an instance
+ of the <code>MaskGenAlgorithm</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the OID
+ <code>id-mgf1</code> defined in <a href="#RFC3447">RFC
+ 3447</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>params</var> field to an instance of the
+ <code>HashAlgorithm</code> ASN.1 type that is
+ identical to the <var>hashAlgorithm</var> field.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to the result of DER-encoding
+ an <code>RSAPrivateKey</code> ASN.1 type, as defined in <a href="#RFC3447">RFC 3447</a>, Appendix A.1.2, that represents the
+ RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>
+ </p>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div>
+ <a href="#RFC5208">RFC 5208</a> specifies that the encoding of
+ this field should be <em>BER</em> encoded in Section 5 (as a "for
+ example"). However, to avoid requiring WebCrypto implementations
+ support BER-encoding and BER-decoding, only <em>DER</em> encodings
+ are produced or accepted.
+ </div>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ul>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the string
+ <code>"RSA"</code>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>SHA-1</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>"RSA-OAEP"</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>SHA-256</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>"RSA-OAEP-256"</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>SHA-384</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>"RSA-OAEP-384"</code>.
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the <a href="#dfn-RsaHashedKeyAlgorithm">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>SHA-512</code>:
+ </dt>
+ <dd>
+ <p>
+ Set the <code>alg</code> attribute of <var>jwk</var> to the string
+ <code>"RSA-OAEP-512"</code>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the attributes <code>n</code> and <code>e</code> of <var>jwk</var>
+ according to the corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.1.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is <code>"private"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Set the attributes named <code>d</code>, <code>p</code>,
+ <code>q</code>, <code>dp</code>, <code>dq</code>, and
+ <code>qi</code> of <var>jwk</var> according to the
+ corresponding definitions in <a href="#jwa">JSON Web
+ Algorithms</a>, Section 6.3.2.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying RSA private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var> is represented by more than two primes, set
+ the attribute named <code>oth</code> of <var>jwk</var>
+ according to the corresponding definition in <a href="#jwa">JSON Web Algorithms</a>, Section 6.3.2.7
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ul>
+ </dd>
+ <dt>Otherwise</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="ecdsa" class="section">
+ <h3>25. ECDSA</h3>
+ <div id="ecdsa-description" class="section">
+ <h4>25.1. Description</h4>
+ <p>
+ The <code>"ECDSA"</code> algorithm identifier is used to perform signing
+ and verification using the ECDSA algorithm specified in
+ [<cite><a href="#X9.62">X9.62</a></cite>].
+ </p>
+ </div>
+ <div id="ecdsa-registration" class="section">
+ <h4>25.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"ECDSA"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sign</td>
+ <td><a href="#dfn-EcdsaParams">EcdsaParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>verify</td>
+ <td><a href="#dfn-EcdsaParams">EcdsaParams</a></td>
+ <td>boolean</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-EcKeyGenParams">EcKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+
+ </tbody>
+ </table>
+ </div>
+ <div id="EcdsaParams-dictionary" class="section">
+ <h4>25.3. EcdsaParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-EcdsaParams">EcdsaParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The hash algorithm to use</span>
- AlgorithmIdentifier <dfn id="dfn-EcdsaParams-hash">hash</dfn>;
+<span class="comment">// The hash algorithm to use</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-EcdsaParams-hash">hash</dfn>;
};
- </code></pre></div></div>
- </div>
- <div id="EcKeyGenParams-dictionary" class="section">
- <h4>20.7.4. EcKeyGenParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+ </code></pre></div></div>
+ </div>
+ <div id="EcKeyGenParams-dictionary" class="section">
+ <h4>25.4. EcKeyGenParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
typedef DOMString <a href="#dfn-NamedCurve">NamedCurve</a>;
dictionary <dfn id="dfn-EcKeyGenParams">EcKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// A named curve</span>
- <a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyGenParams-namedCurve">namedCurve</dfn>;
-};
- </code></pre></div></div>
- <p>
- The <dfn id="dfn-NamedCurve">NamedCurve</dfn> type represents named elliptic curves,
- which are a convenient way to specify the domain parameters of well-known elliptic
- curves. The following values are recognized:
- </p>
- <dl>
- <dt id="dfn-NamedCurve-p256"><code>P-256</code></dt>
- <dd>NIST recommended curve P-256, also known as <code>secp256r1</code>.</dd>
- <dt id="dfn-NamedCurve-p2384"><code>P-384</code></dt>
- <dd>NIST recommended curve P-384, also known as <code>secp384r1</code>.</dd>
- <dt id="dfn-NamedCurve-p521"><code>P-521</code></dt>
- <dd>NIST recommended curve P-521, also known as <code>secp521r1</code>.</dd>
- </dl>
- </div>
- <div id="EcKeyAlgorithm-dictionary" class="section">
- <h4>20.7.5. EcKeyAlgorithm dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-EcKeyAlgorithm">EcKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
- <span class="comment">// The named curve that the key uses</span>
- <a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyAlgorithm-namedCurve">namedCurve</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="EcKeyImportParams-dictionary" class="section">
- <h4>20.7.6. EcKeyImportParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-EcKeyImportParams">EcKeyImportParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// A named curve</span>
- <a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyImportParams-namedCurve">namedCurve</dfn>;
+<span class="comment">// A named curve</span>
+<a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyGenParams-namedCurve">namedCurve</dfn>;
};
- </code></pre></div></div>
- </div>
-
- <div id="ecdsa-operations" class="section">
- <h4>20.7.7. Operations</h4>
- <dl>
- <dt>Sign</dt>
- <dd>
- When signing, the following algorithm should be used:
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcdsaParams">EcdsaParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the properties of <a href="#dfn-EcdsaParams">EcdsaParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlgorithm</var> be the <a href="#dfn-EcdsaParams-hash">hash</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>hashAlgorithm</var> does not describe a
- <a href="#algorithms">registered algorithm</a> that supports the digest
- operation,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>M</var> be the result of performing the digest operation specified by
- <var>hashAlgorithm</var> using <var>message</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>d</var> be the ECDSA private key associated with <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the EC domain parameters associated with
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Perform the ECDSA signing process, as specified in <a href="#X9.62">X9.62</a>,
- Section 7.3, with <var>M</var> as the message, using <var>params</var> as the
- EC domain parameters, and with <var>d</var> as the private key.
- </p>
- </li>
- <li>
- <p>
- Let <var>r</var> and <var>s</var> be the pair of integers resulting from
- performing the ECDSA signing process.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code>.
- </p>
- </li>
- <li>
- <p>
- Convert <var>r</var> to a bitstring and append the sequence of bytes to
- <var>result</var>.
- </p>
- </li>
- <li>
- <p>
- Convert <var>s</var> to a bitstring and append the sequence of bytes to
- <var>result</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Verify</dt>
- <dd>
- When verifying, the following algorithm should be used:
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcdsaParams">EcdsaParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the properties of <a href="#dfn-EcdsaParams">EcdsaParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hashAlgorithm</var> be the <a href="#dfn-EcdsaParams-hash">hash</a>
- member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>hashAlgorithm</var> does not describe a
- <a href="#algorithms">registered algorithm</a> that supports the digest
- operation,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>M</var> be the result of performing the digest operation specified by
- <var>hashAlgorithm</var> using <var>message</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>Q</var> be the ECDSA public key associated with <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the EC domain parameters associated with
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Perform the ECDSA verifying process, as specified in <a href="#X9.62">X9.62</a>, Section 7.4, with <var>M</var> as the received
- message, <var>signature</var> as the received signature and using
- <var>params</var> as the EC domain parameters, and
- <var>Q</var> as the public key.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a boolean indicating whether or not the purported
- signature is valid, with <code>true</code> indicating the signature is valid
- and <code>false</code> indicating it is invalid.
- </p>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcKeyGenParams">EcKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-EcKeyGenParams">EcKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains a value which is not
- one of <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an Elliptic Curve key pair, as defined in [<a href="#X9.62">X9.62</a>]
- with domain parameters for the curve identified by
- the <a href="#dfn-EcKeyGenParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If performing the key generation operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDSA"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-EcKeyGenParams">namedCurve</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the empty list.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
- intersection</a> of <var>usages</var> and <code>[ "sign", "verify" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to be <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to be <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object, as
- defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>Let <var>keyData</var> be the key data to be imported.</p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcKeyImportParams">EcKeyImportParams</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the
- <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
- algorithm over <var>keyData</var>
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is
- not equal to the <code>id-ecPublicKey</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the <code>algorithm</code>
- AlgorithmIdentifier field of <var>spki</var> is absent,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not an instance of the <code>namedCurve</code>
- ASN.1 type defined in <a href="#RFC5480">RFC 5480</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>params</var> is equivalent to the <code>secp256r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-256"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp384r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-384"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp521r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-521"</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is defined, and not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the Elliptic Curve public key identified by
- performing the conversion steps defined in Section 2.2 of <a href="#RFC5480">RFC 5480</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDSA"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurs while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithm field of
- <var>privateKeyInfo</var> is not equal to the
- <code>id-ecPublicKey</code> object identifier defined in <a href="#RFC5480">RFC 5480</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var> is not present,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If the <var>params</var> is not an instance of the
- <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
- 5480</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ecPrivateKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the <code>privateKey</code> field
- of <var>privateKeyInfo</var>, <var>structure</var> as the ASN.1
- <code>ECPrivateKey</code> structure specified in Section 3 of <a href="#RFC5915">RFC 5915</a>, and <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of <var>ecPrivateKey</var> is
- present, and is not an instance of the <code>namedCurve</code> ASN.1
- type defined in <a href="#RFC5480">RFC 5480</a>, or does not contain
- the same object identifier as the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>params</var> is equivalent to the <code>secp256r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-256"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp384r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-384"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp521r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-521"</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is defined, and not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the Elliptic Curve private key identified by
- performing the conversion steps defined in Section 3 of <a href="#RFC5915">RFC 5915</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDSA"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"EC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"sig"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of <a href="#jwk">JSON Web
- Key</a>, or it does not contain all of the specified <var>usages</var>
- values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose value is equal to the
- <code>"crv"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algNamedCurve</var> be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"alg"</code> field is present:</dt>
- <dd>
- Let <var>algNamedCurve</var> be undefined.
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string "ES256":
- </dt>
- <dd>
- Let <var>algNamedCurve</var> be the string <code>P-256</code>.
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string "ES384":
- </dt>
- <dd>
- Let <var>algNamedCurve</var> be the string <code>P-384</code>.
- </dd>
- <dt>
- If the <code>"alg"</code> field is equal to the string "ES521":
- </dt>
- <dd>
- Let <var>algNamedCurve</var> be the string <code>P-521</code>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>algNamedCurve</var> is defined, and is not equal to
- <var>namedCurve</var>, <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"d"</code> field is present:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- Elliptic Curve private key identified by interpreting
- <var>jwk</var> according to Section 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>Key</var> to <code>"private"</code>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- Elliptic Curve public key identified by interpreting
- <var>jwk</var> according to Section 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>Key</var> to <code>"public"</code>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new instance of an <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDSA"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>key</var>
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>key</var> be the <a href="#dfn-CryptoKey">CryptoKey</a> to be
- exported.
- </p>
- </li>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
+ </code></pre></div></div>
+ <p>
+ The <dfn id="dfn-NamedCurve">NamedCurve</dfn> type represents named elliptic curves,
+ which are a convenient way to specify the domain parameters of well-known elliptic
+ curves. The following values are recognized:
+ </p>
+ <dl>
+ <dt id="dfn-NamedCurve-p256"><code>P-256</code></dt>
+ <dd>NIST recommended curve P-256, also known as <code>secp256r1</code>.</dd>
+ <dt id="dfn-NamedCurve-p2384"><code>P-384</code></dt>
+ <dd>NIST recommended curve P-384, also known as <code>secp384r1</code>.</dd>
+ <dt id="dfn-NamedCurve-p521"><code>P-521</code></dt>
+ <dd>NIST recommended curve P-521, also known as <code>secp521r1</code>.</dd>
+ </dl>
+ </div>
+ <div id="EcKeyAlgorithm-dictionary" class="section">
+ <h4>25.5. EcKeyAlgorithm dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-EcKeyAlgorithm">EcKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
+<span class="comment">// The named curve that the key uses</span>
+<a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyAlgorithm-namedCurve">namedCurve</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="EcKeyImportParams-dictionary" class="section">
+ <h4>25.6. EcKeyImportParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-EcKeyImportParams">EcKeyImportParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// A named curve</span>
+<a href="#dfn-NamedCurve">NamedCurve</a> <dfn id="dfn-EcKeyImportParams-namedCurve">namedCurve</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+
+ <div id="ecdsa-operations" class="section">
+ <h4>25.7. Operations</h4>
+ <dl>
+ <dt>Sign</dt>
+ <dd>
+ When signing, the following algorithm should be used:
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlgorithm</var> be the <a href="#dfn-EcdsaParams-hash">hash</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>hashAlgorithm</var> does not describe a
+ <a href="#algorithms">registered algorithm</a> that supports the digest
+ operation,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>M</var> be the result of performing the digest operation specified by
+ <var>hashAlgorithm</var> using <var>message</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>d</var> be the ECDSA private key associated with <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the EC domain parameters associated with
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the ECDSA signing process, as specified in <a href="#X9.62">X9.62</a>,
+ Section 7.3, with <var>M</var> as the message, using <var>params</var> as the
+ EC domain parameters, and with <var>d</var> as the private key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>r</var> and <var>s</var> be the pair of integers resulting from
+ performing the ECDSA signing process.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Convert <var>r</var> to a bitstring and append the sequence of bytes to
+ <var>result</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Convert <var>s</var> to a bitstring and append the sequence of bytes to
+ <var>result</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Verify</dt>
+ <dd>
+ When verifying, the following algorithm should be used:
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hashAlgorithm</var> be the <a href="#dfn-EcdsaParams-hash">hash</a>
+ member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>hashAlgorithm</var> does not describe a
+ <a href="#algorithms">registered algorithm</a> that supports the digest
+ operation,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>M</var> be the result of performing the digest operation specified by
+ <var>hashAlgorithm</var> using <var>message</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>Q</var> be the ECDSA public key associated with <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the EC domain parameters associated with
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the ECDSA verifying process, as specified in <a href="#X9.62">X9.62</a>, Section 7.4, with <var>M</var> as the received
+ message, <var>signature</var> as the received signature and using
+ <var>params</var> as the EC domain parameters, and
+ <var>Q</var> as the public key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a boolean indicating whether or not the purported
+ signature is valid, with <code>true</code> indicating the signature is valid
+ and <code>false</code> indicating it is invalid.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains a value which is not
+ one of <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an Elliptic Curve key pair, as defined in [<a href="#X9.62">X9.62</a>]
+ with domain parameters for the curve identified by
+ the <a href="#dfn-EcKeyGenParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the key generation operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDSA"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-EcKeyGenParams">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the empty list.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be the <a href="#concept-usage-intersection">usage
+ intersection</a> of <var>usages</var> and <code>[ "sign", "verify" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to be <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to be <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object, as
+ defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>Let <var>keyData</var> be the key data to be imported.</p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the
+ <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
+ algorithm over <var>keyData</var>
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is
+ not equal to the <code>id-ecPublicKey</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the <code>algorithm</code>
+ AlgorithmIdentifier field of <var>spki</var> is absent,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not an instance of the <code>namedCurve</code>
+ ASN.1 type defined in <a href="#RFC5480">RFC 5480</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp256r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-256"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp384r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-384"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp521r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-521"</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is defined, and not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the Elliptic Curve public key identified by
+ performing the conversion steps defined in Section 2.2 of <a href="#RFC5480">RFC 5480</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDSA"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurs while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithm field of
+ <var>privateKeyInfo</var> is not equal to the
+ <code>id-ecPublicKey</code> object identifier defined in <a href="#RFC5480">RFC 5480</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var> is not present,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <var>params</var> is not an instance of the
+ <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
+ 5480</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ecPrivateKey</var> be the result of performing the <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the <code>privateKey</code> field
+ of <var>privateKeyInfo</var>, <var>structure</var> as the ASN.1
+ <code>ECPrivateKey</code> structure specified in Section 3 of <a href="#RFC5915">RFC 5915</a>, and <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of <var>ecPrivateKey</var> is
+ present, and is not an instance of the <code>namedCurve</code> ASN.1
+ type defined in <a href="#RFC5480">RFC 5480</a>, or does not contain
+ the same object identifier as the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp256r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-256"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp384r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-384"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp521r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-521"</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is defined, and not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the Elliptic Curve private key identified by
+ performing the conversion steps defined in Section 3 of <a href="#RFC5915">RFC 5915</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDSA"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"EC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"sig"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of <a href="#jwk">JSON Web
+ Key</a>, or it does not contain all of the specified <var>usages</var>
+ values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose value is equal to the
+ <code>"crv"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algNamedCurve</var> be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"alg"</code> field is present:</dt>
+ <dd>
+ Let <var>algNamedCurve</var> be undefined.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string "ES256":
+ </dt>
+ <dd>
+ Let <var>algNamedCurve</var> be the string <code>P-256</code>.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string "ES384":
+ </dt>
+ <dd>
+ Let <var>algNamedCurve</var> be the string <code>P-384</code>.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field is equal to the string "ES521":
+ </dt>
+ <dd>
+ Let <var>algNamedCurve</var> be the string <code>P-521</code>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>algNamedCurve</var> is defined, and is not equal to
+ <var>namedCurve</var>, <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"d"</code> field is present:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ Elliptic Curve private key identified by interpreting
+ <var>jwk</var> according to Section 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>Key</var> to <code>"private"</code>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ Elliptic Curve public key identified by interpreting
+ <var>jwk</var> according to Section 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>Key</var> to <code>"public"</code>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new instance of an <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDSA"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>key</var> be the <a href="#dfn-CryptoKey">CryptoKey</a> to be
+ exported.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a href="#concept-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> object identifier to the OID
+ <code>1.2.840.10045.2.1</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>namedCurve</code> ASN.1 type as follows:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp256r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp384r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-521"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp521r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> field to the octet string that
+ represents the Elliptic Curve public key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> according to the encoding rules specified in
+ Section 2.2 of <a href="#RFC5480">RFC 5480</a> and using the
+ uncompressed form.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a href="#concept-encode-a-privateKeyInfo">encoding a
+ privateKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>version</var> field to <code>0</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to an
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> object identifier to the OID
+ <code>1.2.840.10045.2.1</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>namedCurve</code> ASN.1 type as follows:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp256r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp384r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-521"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp521r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to the result of DER-encoding
+ an instance of the <code>ECPrivateKey</code> structure defined in
+ Section 3 of <a href="#RFC5915">RFC 5915</a> for the Elliptic
+ Curve private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> and that conforms to the following:
+ </p>
+ <ul>
+ <li>
+ <p>
+ The <var>parameters</var> field is present, and is equivalent
+ to the <var>parameters</var> field of the
+ <var>privateKeyAlgorithm</var> field of this
+ <code>PrivateKeyInfo</code> ASN.1 structure.
+ </p>
+ </li>
+ <li>
+ <p>
+ The <var>publicKey</var> field is present and represents the
+ Elliptic Curve public key associated with the Elliptic Curve
+ private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to
+ <code>"EC"</code>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-256</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-256"</code>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-384</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-384"</code>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-521</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-521"</code>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>x</code> attribute of <var>jwk</var> according to the
+ definition in Section 6.2.1.2 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>y</code> attribute of <var>jwk</var> according to the
+ definition in Section 6.2.1.3 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a href="#concept-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> object identifier to the OID
- <code>1.2.840.10045.2.1</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>namedCurve</code> ASN.1 type as follows:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-256"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp256r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-384"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp384r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-521"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp521r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- </dl>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> field to the octet string that
- represents the Elliptic Curve public key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> according to the encoding rules specified in
- Section 2.2 of <a href="#RFC5480">RFC 5480</a> and using the
- uncompressed form.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a href="#concept-encode-a-privateKeyInfo">encoding a
- privateKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>version</var> field to <code>0</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to an
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> object identifier to the OID
- <code>1.2.840.10045.2.1</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>namedCurve</code> ASN.1 type as follows:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-256"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp256r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-384"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp384r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-521"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp521r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- </dl>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to the result of DER-encoding
- an instance of the <code>ECPrivateKey</code> structure defined in
- Section 3 of <a href="#RFC5915">RFC 5915</a> for the Elliptic
- Curve private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> and that conforms to the following:
- </p>
- <ul>
- <li>
- <p>
- The <var>parameters</var> field is present, and is equivalent
- to the <var>parameters</var> field of the
- <var>privateKeyAlgorithm</var> field of this
- <code>PrivateKeyInfo</code> ASN.1 structure.
- </p>
- </li>
- <li>
- <p>
- The <var>publicKey</var> field is present and represents the
- Elliptic Curve public key associated with the Elliptic Curve
- private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to
- <code>"EC"</code>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-256</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-256"</code>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-384</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-384"</code>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-521</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-521"</code>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>x</code> attribute of <var>jwk</var> according to the
- definition in Section 6.2.1.2 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>y</code> attribute of <var>jwk</var> according to the
- definition in Section 6.2.1.3 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>private</code>
- </dt>
- <dd>
- <p>
- Set the <code>d</code> attribute of <var>jwk</var> according to
- the definition in Section 6.2.2.1 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="ecdh" class="section">
- <h3>20.8. ECDH</h3>
- <div id="ecdh-description" class="section">
- <h4>20.8.1. Description</h4>
- <p>
- This describes using Elliptic Curve Diffie-Hellman (ECDH) for key generation and key
- agreement, as specified by <a href="#X9.63">X9.63</a>.
- </p>
- </div>
- <div id="ecdh-registration" class="section">
- <h4>20.8.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"ECDH"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-EcKeyGenParams">EcKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>deriveBits</td>
- <td><a href="#dfn-EcdhKeyDeriveParams">EcdhKeyDeriveParams</a></td>
- <td>Octet string</td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-EcKeyImportParams">EcKeyImportParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="dh-EcdhKeyDeriveParams" class="section">
- <h4>20.8.3. EcdhKeyDeriveParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+ of <var>key</var> is <code>private</code>
+ </dt>
+ <dd>
+ <p>
+ Set the <code>d</code> attribute of <var>jwk</var> according to
+ the definition in Section 6.2.2.1 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to the <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="ecdh" class="section">
+ <h3>26. ECDH</h3>
+ <div id="ecdh-description" class="section">
+ <h4>26.1. Description</h4>
+ <p>
+ This describes using Elliptic Curve Diffie-Hellman (ECDH) for key generation and key
+ agreement, as specified by <a href="#X9.63">X9.63</a>.
+ </p>
+ </div>
+ <div id="ecdh-registration" class="section">
+ <h4>26.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"ECDH"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-EcKeyGenParams">EcKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>deriveBits</td>
+ <td><a href="#dfn-EcdhKeyDeriveParams">EcdhKeyDeriveParams</a></td>
+ <td>Octet string</td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-EcKeyImportParams">EcKeyImportParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="dh-EcdhKeyDeriveParams" class="section">
+ <h4>26.3. EcdhKeyDeriveParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
typedef Uint8Array <dfn id="dfn-ECPoint">ECPoint</dfn>;
dictionary <dfn id="dfn-EcdhKeyDeriveParams">EcdhKeyDeriveParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The peer's EC public key.</span>
- <a href="#dfn-CryptoKey">CryptoKey</a> <dfn id="dfn-EcdhKeyDeriveParams-public">public</dfn>;
+<span class="comment">// The peer's EC public key.</span>
+<a href="#dfn-CryptoKey">CryptoKey</a> <dfn id="dfn-EcdhKeyDeriveParams-public">public</dfn>;
};
- </code></pre></div></div>
- </div>
- <div id="ecdh-operations" class="section">
- <h4>20.8.4. Operations</h4>
- <dl>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcKeyGenParams">EcKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-EcKeyGenParams">EcKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains a value which is not
- one of <code>"deriveKey"</code> or <code>"deriveBits"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an Elliptic Curve key pair, as defined in [<a href="#X9.63">X9.63</a>] with domain parameters for the curve identified by
- the <a href="#dfn-EcKeyGenParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-Algorithm-name">name</a> member of
- <var>algorithm</var> to <code>"ECDH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-EcKeyGenParams">namedCurve</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the empty list.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be the
- <a href="#concept-usage-intersection">usage intersection</a> of
- <var>usages</var> and <code>[ "deriveKey", "deriveBits" ]</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to be <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to be <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object, as
- defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- <dt>Derive Bits</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcdhKeyDeriveParams">EcdhKeyDeriveParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-EcdhKeyDeriveParams">EcdhKeyDeriveParams</a> are not present in
- <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be the
- <a href="#dfn-EcdhKeyDeriveParams-public">public</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> is not <code>"ECDH"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> is not equal to the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a> property of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
- named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the ECDH primitive specified in <a href="#X9.63">X9.63</a> Section
- 5.4.1 with <var>key</var> as the EC private key <var>d</var> and the EC public
- key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
- internal slot of <var>publicKey</var> as the EC public key <var>Q</var>.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>secret</var> be the result of applying the field element to
- octet string conversion defined in Section ? of <a href="#X9.63">X9.63</a>
- to the output of the ECDH primitive.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>length</var> is null:</dt>
- <dd>Return <var>secret</var></dd>
- <dt>Otherwise:</dt>
- <dd>
- <dl class="switch">
- <dt>
- If the length of <var>secret</var> in bits is less than
- <var>length</var>:
- </dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>Return the first <var>length</var> bits of <var>secret</var>.</dd>
- </dl>
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
-
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>Let <var>keyData</var> be the key data to be imported.</p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-EcKeyImportParams">EcKeyImportParams</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the
- <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
- algorithm over <var>keyData</var>
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is
- not equal to the <code>id-ecPublicKey</code> or <code>id-ecDH</code>
- object identifiers defined in <a href="#RFC5480">RFC 5480</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the <code>algorithm</code>
- AlgorithmIdentifier field of <var>spki</var> is absent,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not an instance of the
- <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
- 5480</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>params</var> is equivalent to the <code>secp256r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-256"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp384r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-384"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp521r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-521"</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is defined, and not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the Elliptic Curve public key identified by
- performing the conversion steps defined in Section 2.2 of <a href="#RFC5480">RFC 5480</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurs while parsing,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithm field of
- <var>privateKeyInfo</var> is not equal to the
- <code>id-ecPublicKey</code> or <code>id-ecDH</code> object identifiers
- defined in <a href="#RFC5480">RFC 5480</a>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var> is not present,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If the <var>params</var> is not an instance of the
- <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
- 5480</a>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ecPrivateKey</var> be the result of performing the
- <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
- algorithm, with <var>data</var> as the <code>privateKey</code> field
- of <var>privateKeyInfo</var>, <var>structure</var> as the ASN.1
- <code>ECPrivateKey</code> structure specified in Section 3 of
- <a href="#RFC5915">RFC 5915</a>, and <var>exactData</var> set to true.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of <var>ecPrivateKey</var> is
- present, and is not an instance of the <code>namedCurve</code> ASN.1
- type defined in <a href="#RFC5480">RFC 5480</a>, or does not contain
- the same object identifier as the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
- of <var>privateKeyInfo</var>,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose initial value is
- undefined.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>params</var> is equivalent to the <code>secp256r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-256"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp384r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-384"</code>.
- </p>
- </dd>
- <dt>
- If <var>params</var> is equivalent to the <code>secp521r1</code>
- object identifier defined in <a href="#RFC5480">RFC 5480</a>:
- </dt>
- <dd>
- <p>
- Set <var>namedCurve</var> <code>"P-521"</code>.
- </p>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is defined, and not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object that represents the Elliptic Curve private key identified by
- performing the conversion steps defined in Section 3 of <a href="#RFC5915">RFC 5915</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"private"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is
- to <code>"EC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of <a href="#jwk">JSON Web
- Key</a>, or it does not contain all of the specified <var>usages</var>
- values, then <a href="#concept-return-an-error">return an error</a>
- named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>namedCurve</var> be a string whose value is equal to the
- <code>"crv"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>namedCurve</var> is not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <code>"d"</code> field is present:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- Elliptic Curve private key identified by interpreting
- <var>jwk</var> according to Section 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>Key</var> to <code>"private"</code>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of Section
- 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
- Elliptic Curve public key identified by interpreting
- <var>jwk</var> according to Section 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
- internal slot of <var>Key</var> to <code>"public"</code>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new instance of an <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to <var>namedCurve</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If any of the members of <a href="#dfn-EcKeyImportParams">EcKeyImportParams</a> are not present in
- <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a>
- member of <var>normalizedAlgorithm</var> is not a
- <a href="#dfn-NamedCurve">named curve</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> is not the empty list,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>extractable</var> is false,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>Q</var> be the elliptic curve point on the curve identified
- by the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a>
- member of <var>normalizedAlgorithm</var> identified by interpreting
- <var>keyData</var> according to <a href="#X9.62">X9.62</a> Annex A.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"ECDH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-namedCurve">namedCurve</a>
- attribute of <var>algorithm</var> to equal the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal
- slot of <var>key</var> to <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
+ </code></pre></div></div>
+ </div>
+ <div id="ecdh-operations" class="section">
+ <h4>26.4. Operations</h4>
+ <dl>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If any of the members of <a href="#dfn-EcKeyGenParams">EcKeyGenParams</a> are
+ not present in <var>normalizedAlgorithm</var>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains a value which is not
+ one of <code>"deriveKey"</code> or <code>"deriveBits"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an Elliptic Curve key pair, as defined in [<a href="#X9.63">X9.63</a>] with domain parameters for the curve identified by
+ the <a href="#dfn-EcKeyGenParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>algorithm</var> to <code>"ECDH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-EcKeyGenParams">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the empty list.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be the
+ <a href="#concept-usage-intersection">usage intersection</a> of
+ <var>usages</var> and <code>[ "deriveKey", "deriveBits" ]</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to be <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to be <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object, as
+ defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Derive Bits</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be the
+ <a href="#dfn-EcdhKeyDeriveParams-public">public</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> is not <code>"ECDH"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> is not equal to the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a> property of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
+ named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the ECDH primitive specified in <a href="#X9.63">X9.63</a> Section
+ 5.4.1 with <var>key</var> as the EC private key <var>d</var> and the EC public
+ key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
+ internal slot of <var>publicKey</var> as the EC public key <var>Q</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>secret</var> be the result of applying the field element to
+ octet string conversion defined in Section ? of <a href="#X9.63">X9.63</a>
+ to the output of the ECDH primitive.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>length</var> is null:</dt>
+ <dd>Return <var>secret</var></dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <dl class="switch">
+ <dt>
+ If the length of <var>secret</var> in bits is less than
+ <var>length</var>:
+ </dt>
+ <dd>
<a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>key</var>
- </p>
- </li>
- </ol>
- </dd>
-
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>key</var> be the <a href="#dfn-CryptoKey">CryptoKey</a> to be
- exported.
- </p>
- </li>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"spki"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of <a href="#concept-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 type with the following
- properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> object identifier to the OID
- <code>1.3.132.112</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>namedCurve</code> ASN.1 type as follows:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-256"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp256r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-384"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp384r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-521"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp521r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- </dl>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> field to the octet string that
- represents the Elliptic Curve public key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> according to the encoding rules specified in
- Section 2.2 of <a href="#RFC5480">RFC 5480</a> and using the
- uncompressed form.
- </p>
- </li>
- </ul>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of <a href="#concept-encode-a-privateKeyInfo">encoding a
- privateKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>version</var> field to <code>0</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to an
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> object identifier to the OID
- <code>1.3.132.112</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>namedCurve</code> ASN.1 type as follows:
- </p>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-256"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp256r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-384"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp384r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var> is <code>"P-521"</code>:
- </dt>
- <dd>
- <p>
- Let the <var>namedCurve</var> be the object identifier
- <code>secp521r1</code> defined in <a href="#RFC5480">RFC
- 5480</a>
- </p>
- </dd>
- </dl>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to the result of DER-encoding
- an instance of the <code>ECPrivateKey</code> structure defined in
- Section 3 of <a href="#RFC5915">RFC 5915</a> for the Elliptic
- Curve private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> and that conforms to the following:
- </p>
- <ul>
- <li>
- <p>
- The <var>parameters</var> field is present, and is equivalent
- to the <var>parameters</var> field of the
- <var>privateKeyAlgorithm</var> field of this
- <code>PrivateKeyInfo</code> ASN.1 structure.
- </p>
- </li>
- <li>
- <p>
- The <var>publicKey</var> field is present and represents the
- Elliptic Curve public key associated with the Elliptic Curve
- private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to
- <code>"EC"</code>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-256</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-256"</code>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-384</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-384"</code>
- </dd>
- <dt>
- If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
- of <var>key</var> is <code>P-521</code>:
- </dt>
- <dd>
- Set the <code>crv</code> attribute of <var>jwk</var> to
- <code>"P-521"</code>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>x</code> attribute of <var>jwk</var> according to the
- definition in Section 6.2.1.2 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>y</code> attribute of <var>jwk</var> according to the
- definition in Section 6.2.1.3 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>private</code>
- </dt>
- <dd>
- <p>
- Set the <code>d</code> attribute of <var>jwk</var> according to the
- definition in Section 6.2.2.1 of <a href="#jwa">JSON Web
- Algorithms</a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- <dt>
- If <var>format</var> is <code>"raw"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be an octet string representing the Elliptic Curve
- point <var>Q</var> represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var> according to <a href="#X9.62">X9.62</a> Annex A.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <p>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </p>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="aes-ctr" class="section">
- <h3>20.9. AES-CTR</h3>
- <div id="aes-ctr-description" class="section">
- <h4>20.9.1. Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"AES-CTR"</code> algorithm identifier is used to perform
- encryption and decryption using AES in Counter mode,
- as described in NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>].
- </p>
- </div>
- <div id="aes-ctr-registration" class="section">
- <h4>20.9.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-CTR"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>encrypt</td>
- <td><a href="#dfn-AesCtrParams">AesCtrParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>decrypt</td>
- <td><a href="#dfn-AesCtrParams">AesCtrParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
-
- <div id="aes-ctr-params" class="section">
- <h4>20.9.3. AesCtrParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-AesCtrParams">AesCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The initial value of the counter block. counter <span class="RFC2119">MUST</span> be 16 bytes
- // (the AES block size). The counter bits are the rightmost length
- // bits of the counter block. The rest of the counter block is for
- // the nonce. The counter bits are incremented using the standard
- // incrementing function specified in NIST SP 800-38A Appendix B.1:
- // the counter bits are interpreted as a big-endian integer and
- // incremented by one.</span>
- CryptoOperationData <dfn id="dfn-AesCtrParams-counter">counter</dfn>;
- <span class="comment">// The length, in bits, of the rightmost part of the counter block
- // that is incremented.</span>
- [EnforceRange] octet <dfn id="dfn-AesCtrParams-length">length</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="AesKeyAlgorithm-dictionary" class="section">
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-AesKeyAlgorithm">AesKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
- <span class="comment">// The length, in bits, of the key.</span>
- unsigned short <dfn id="dfn-AesKeyAlgorithm-length">length</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="aes-keygen-params" class="section">
- <h4>20.9.5. AesKeyGenParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-AesKeyGenParams">AesKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The length, in bits, of the key.</span>
- [EnforceRange] unsigned short <dfn id="dfn-AesKeyGenParams-length">length</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="aes-derivedkey-params" class="section">
- <h4>20.9.6. AesDerivedKeyParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-AesDerivedKeyParams">AesDerivedKeyParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The length, in bits, of the key.</span>
- [EnforceRange] unsigned short <dfn id="dfn-AesDerivedKeyParams-length">length</dfn>;
-};
- </code></pre></div></div>
- </div>
-
- <div id="aes-ctr-operations" class="section">
- <h4>20.9.7. Operations</h4>
- <dl>
- <dt>Encrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCtrParams">AesCtrParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-ctr-params">AesCtrParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCtrParams-counter">counter</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCtrParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is zero or is greater
- than 128,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ciphertext</var> be the result of performing the CTR Encryption
- operation described in Section 6.5 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCtrParams-counter">counter</a> member of
- <var>normalizedAlgorithm</var> as the initial value of the counter block, the
- <a href="#dfn-AesCtrParams-length">length</a> member of
- <var>normalizedAlgorithm</var> as the input parameter <var>m</var> to the
- standard counter block incrementing function defined in Appendix B.1 of NIST SP
- 800-38A [<a href="#SP800-38A">SP800-38A</a>] and <a href="#concept-contents-of-arraybuffer">the contents of
- <var>plaintext</var></a> as the input plaintext.
- </p>
- </li>
- <li>
- <p>
- Return <var>ciphertext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Decrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCtrParams">AesCtrParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-ctr-params">AesCtrParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCtrParams-counter">counter</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCtrParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is zero or is greater
- than 128,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>plaintext</var> be the result of performing the CTR Decryption
- operation described in Section 6.5 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCtrParams-counter">counter</a> member of
- <var>normalizedAlgorithm</var> as the initial value of the counter block, the
- <a href="#dfn-AesCtrParams-length">length</a> member of
- <var>normalizedAlgorithm</var> as the input parameter <var>m</var> to the
- standard counter block incrementing function defined in Appendix B.1 of NIST SP
- 800-38A [<a href="#SP800-38A">SP800-38A</a>] and <a href="#concept-contents-of-arraybuffer">the contents of
- <var>ciphertext</var></a> as the input ciphertext.
- </p>
- </li>
- <li>
- <p>
- Return <var>plaintext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an AES key of length
- equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CTR"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128CTR"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192CTR"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256CTR"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>Return the first <var>length</var> bits of <var>secret</var>.</dd>
+ </dl>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>Let <var>keyData</var> be the key data to be imported.</p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the
+ <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a>
+ algorithm over <var>keyData</var>
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is
+ not equal to the <code>id-ecPublicKey</code> or <code>id-ecDH</code>
+ object identifiers defined in <a href="#RFC5480">RFC 5480</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the <code>algorithm</code>
+ AlgorithmIdentifier field of <var>spki</var> is absent,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not an instance of the
+ <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
+ 5480</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp256r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-256"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp384r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-384"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp521r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-521"</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
<a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is defined, and not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the Elliptic Curve public key identified by
+ performing the conversion steps defined in Section 2.2 of <a href="#RFC5480">RFC 5480</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurs while parsing,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithm field of
+ <var>privateKeyInfo</var> is not equal to the
+ <code>id-ecPublicKey</code> or <code>id-ecDH</code> object identifiers
+ defined in <a href="#RFC5480">RFC 5480</a>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var> is not present,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <var>params</var> is not an instance of the
+ <code>namedCurve</code> ASN.1 type defined in <a href="#RFC5480">RFC
+ 5480</a>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ecPrivateKey</var> be the result of performing the
+ <a href="#concept-parse-an-asn1-structure">parse an ASN.1 structure</a>
+ algorithm, with <var>data</var> as the <code>privateKey</code> field
+ of <var>privateKeyInfo</var>, <var>structure</var> as the ASN.1
+ <code>ECPrivateKey</code> structure specified in Section 3 of
+ <a href="#RFC5915">RFC 5915</a>, and <var>exactData</var> set to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of <var>ecPrivateKey</var> is
+ present, and is not an instance of the <code>namedCurve</code> ASN.1
+ type defined in <a href="#RFC5480">RFC 5480</a>, or does not contain
+ the same object identifier as the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field
+ of <var>privateKeyInfo</var>,
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose initial value is
+ undefined.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp256r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-256"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp384r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-384"</code>.
+ </p>
+ </dd>
+ <dt>
+ If <var>params</var> is equivalent to the <code>secp521r1</code>
+ object identifier defined in <a href="#RFC5480">RFC 5480</a>:
+ </dt>
+ <dd>
+ <p>
+ Set <var>namedCurve</var> <code>"P-521"</code>.
+ </p>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is defined, and not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object that represents the Elliptic Curve private key identified by
+ performing the conversion steps defined in Section 3 of <a href="#RFC5915">RFC 5915</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"private"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is
+ to <code>"EC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of <a href="#jwk">JSON Web
+ Key</a>, or it does not contain all of the specified <var>usages</var>
+ values, then <a href="#concept-return-an-error">return an error</a>
+ named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>namedCurve</var> be a string whose value is equal to the
+ <code>"crv"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>namedCurve</var> is not equal to the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <code>"d"</code> field is present:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ Elliptic Curve private key identified by interpreting
+ <var>jwk</var> according to Section 6.2.2 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>Key</var> to <code>"private"</code>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of Section
+ 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object that represents the
+ Elliptic Curve public key identified by interpreting
+ <var>jwk</var> according to Section 6.2.1 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]]
+ internal slot of <var>Key</var> to <code>"public"</code>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new instance of an <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to <var>namedCurve</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If any of the members of <a href="#dfn-EcKeyImportParams">EcKeyImportParams</a> are not present in
+ <var>normalizedAlgorithm</var>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a>
+ member of <var>normalizedAlgorithm</var> is not a
+ <a href="#dfn-NamedCurve">named curve</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> is not the empty list,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>extractable</var> is false,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>Q</var> be the elliptic curve point on the curve identified
+ by the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a>
+ member of <var>normalizedAlgorithm</var> identified by interpreting
+ <var>keyData</var> according to <a href="#X9.62">X9.62</a> Annex A.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-EcKeyAlgorithm">EcKeyAlgorithm</a> object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"ECDH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of <var>algorithm</var> to equal the <a href="#dfn-EcKeyImportParams-namedCurve">namedCurve</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal
+ slot of <var>key</var> to <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
<a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code> object representing an AES key with
- value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CTR"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128CTR"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192CTR"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256CTR"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="aes-cbc" class="section">
- <h3>20.10. AES-CBC</h3>
- <div id="aes-cbc-description" class="section">
- <h4>20.10.1. Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"AES-CBC"</code> algorithm identifier is used to perform
- encryption and decryption using AES in Cipher Block Chaining mode,
- as described in NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>].
- </p>
- <p>
- When operating in CBC mode, messages that are not exact multiples
- of the AES block size (16 bytes) can be padded under a variety of
- padding schemes. In the Web Crypto API, the only padding mode that
- is supported is that of PKCS#7, as described by
- Section 10.3, step 2, of RFC 2315 [<a href="#RFC2315">RFC2315</a>].
- </p>
- </div>
- <div id="aes-cbc-registration" class="section">
- <h4>20.10.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-CBC"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>encrypt</td>
- <td><a href="#dfn-AesCbcParams">AesCbcParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>decrypt</td>
- <td><a href="#dfn-AesCbcParams">AesCbcParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="aes-cbc-params" class="section">
- <h4>20.10.3. AesCbcParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>
+ </p>
+ </li>
+ </ol>
+ </dd>
+
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>key</var> be the <a href="#dfn-CryptoKey">CryptoKey</a> to be
+ exported.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"spki"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of <a href="#concept-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 type with the following
+ properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> object identifier to the OID
+ <code>1.3.132.112</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>namedCurve</code> ASN.1 type as follows:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp256r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp384r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-521"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp521r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> field to the octet string that
+ represents the Elliptic Curve public key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> according to the encoding rules specified in
+ Section 2.2 of <a href="#RFC5480">RFC 5480</a> and using the
+ uncompressed form.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"pkcs8"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of <a href="#concept-encode-a-privateKeyInfo">encoding a
+ privateKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>version</var> field to <code>0</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to an
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 type with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> object identifier to the OID
+ <code>1.3.132.112</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>namedCurve</code> ASN.1 type as follows:
+ </p>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-256"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp256r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-384"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp384r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var> is <code>"P-521"</code>:
+ </dt>
+ <dd>
+ <p>
+ Let the <var>namedCurve</var> be the object identifier
+ <code>secp521r1</code> defined in <a href="#RFC5480">RFC
+ 5480</a>
+ </p>
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to the result of DER-encoding
+ an instance of the <code>ECPrivateKey</code> structure defined in
+ Section 3 of <a href="#RFC5915">RFC 5915</a> for the Elliptic
+ Curve private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> and that conforms to the following:
+ </p>
+ <ul>
+ <li>
+ <p>
+ The <var>parameters</var> field is present, and is equivalent
+ to the <var>parameters</var> field of the
+ <var>privateKeyAlgorithm</var> field of this
+ <code>PrivateKeyInfo</code> ASN.1 structure.
+ </p>
+ </li>
+ <li>
+ <p>
+ The <var>publicKey</var> field is present and represents the
+ Elliptic Curve public key associated with the Elliptic Curve
+ private key represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to
+ <code>"EC"</code>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-256</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-256"</code>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-384</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-384"</code>
+ </dd>
+ <dt>
+ If the <a href="#dfn-EcKeyAlgorithm-namedCurve">namedCurve</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot
+ of <var>key</var> is <code>P-521</code>:
+ </dt>
+ <dd>
+ Set the <code>crv</code> attribute of <var>jwk</var> to
+ <code>"P-521"</code>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>x</code> attribute of <var>jwk</var> according to the
+ definition in Section 6.2.1.2 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>y</code> attribute of <var>jwk</var> according to the
+ definition in Section 6.2.1.3 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is <code>private</code>
+ </dt>
+ <dd>
+ <p>
+ Set the <code>d</code> attribute of <var>jwk</var> according to the
+ definition in Section 6.2.2.1 of <a href="#jwa">JSON Web
+ Algorithms</a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ If <var>format</var> is <code>"raw"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be an octet string representing the Elliptic Curve
+ point <var>Q</var> represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var> according to <a href="#X9.62">X9.62</a> Annex A.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <p>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </p>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="aes-ctr" class="section">
+ <h3>27. AES-CTR</h3>
+ <div id="aes-ctr-description" class="section">
+ <h4>27.1. Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-CTR"</code> algorithm identifier is used to perform
+ encryption and decryption using AES in Counter mode,
+ as described in NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>].
+ </p>
+ </div>
+ <div id="aes-ctr-registration" class="section">
+ <h4>27.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-CTR"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>encrypt</td>
+ <td><a href="#dfn-AesCtrParams">AesCtrParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>decrypt</td>
+ <td><a href="#dfn-AesCtrParams">AesCtrParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <div id="aes-ctr-params" class="section">
+ <h4>27.3. AesCtrParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-AesCtrParams">AesCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The initial value of the counter block. counter <span class="RFC2119">MUST</span> be 16 bytes
+// (the AES block size). The counter bits are the rightmost length
+// bits of the counter block. The rest of the counter block is for
+// the nonce. The counter bits are incremented using the standard
+// incrementing function specified in NIST SP 800-38A Appendix B.1:
+// the counter bits are interpreted as a big-endian integer and
+// incremented by one.</span>
+CryptoOperationData <dfn id="dfn-AesCtrParams-counter">counter</dfn>;
+<span class="comment">// The length, in bits, of the rightmost part of the counter block
+// that is incremented.</span>
+[EnforceRange] octet <dfn id="dfn-AesCtrParams-length">length</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="AesKeyAlgorithm-dictionary" class="section">
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-AesKeyAlgorithm">AesKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
+<span class="comment">// The length, in bits, of the key.</span>
+unsigned short <dfn id="dfn-AesKeyAlgorithm-length">length</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="aes-keygen-params" class="section">
+ <h4>27.5. AesKeyGenParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-AesKeyGenParams">AesKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The length, in bits, of the key.</span>
+[EnforceRange] unsigned short <dfn id="dfn-AesKeyGenParams-length">length</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="aes-derivedkey-params" class="section">
+ <h4>27.6. AesDerivedKeyParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-AesDerivedKeyParams">AesDerivedKeyParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The length, in bits, of the key.</span>
+[EnforceRange] unsigned short <dfn id="dfn-AesDerivedKeyParams-length">length</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+
+ <div id="aes-ctr-operations" class="section">
+ <h4>27.7. Operations</h4>
+ <dl>
+ <dt>Encrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCtrParams-counter">counter</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCtrParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is zero or is greater
+ than 128,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ciphertext</var> be the result of performing the CTR Encryption
+ operation described in Section 6.5 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCtrParams-counter">counter</a> member of
+ <var>normalizedAlgorithm</var> as the initial value of the counter block, the
+ <a href="#dfn-AesCtrParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> as the input parameter <var>m</var> to the
+ standard counter block incrementing function defined in Appendix B.1 of NIST SP
+ 800-38A [<a href="#SP800-38A">SP800-38A</a>] and <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>plaintext</var></a> as the input plaintext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>ciphertext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Decrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCtrParams-counter">counter</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCtrParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is zero or is greater
+ than 128,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>plaintext</var> be the result of performing the CTR Decryption
+ operation described in Section 6.5 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCtrParams-counter">counter</a> member of
+ <var>normalizedAlgorithm</var> as the initial value of the counter block, the
+ <a href="#dfn-AesCtrParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> as the input parameter <var>m</var> to the
+ standard counter block incrementing function defined in Appendix B.1 of NIST SP
+ 800-38A [<a href="#SP800-38A">SP800-38A</a>] and <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>ciphertext</var></a> as the input ciphertext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>plaintext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not equal to one of
+ 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an AES key of length
+ equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CTR"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"oct"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128CTR"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192CTR"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256CTR"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code> object representing an AES key with
+ value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CTR"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128CTR"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192CTR"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256CTR"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="aes-cbc" class="section">
+ <h3>28. AES-CBC</h3>
+ <div id="aes-cbc-description" class="section">
+ <h4>28.1. Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-CBC"</code> algorithm identifier is used to perform
+ encryption and decryption using AES in Cipher Block Chaining mode,
+ as described in NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>].
+ </p>
+ <p>
+ When operating in CBC mode, messages that are not exact multiples
+ of the AES block size (16 bytes) can be padded under a variety of
+ padding schemes. In the Web Crypto API, the only padding mode that
+ is supported is that of PKCS#7, as described by
+ Section 10.3, step 2, of RFC 2315 [<a href="#RFC2315">RFC2315</a>].
+ </p>
+ </div>
+ <div id="aes-cbc-registration" class="section">
+ <h4>28.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-CBC"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>encrypt</td>
+ <td><a href="#dfn-AesCbcParams">AesCbcParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>decrypt</td>
+ <td><a href="#dfn-AesCbcParams">AesCbcParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="aes-cbc-params" class="section">
+ <h4>28.3. AesCbcParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-AesCbcParams">AesCbcParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The initialization vector. <span class="RFC2119">MUST</span> be 16 bytes.</span>
- CryptoOperationData <dfn id="dfn-AesCbcParams-iv">iv</dfn>;
+<span class="comment">// The initialization vector. <span class="RFC2119">MUST</span> be 16 bytes.</span>
+CryptoOperationData <dfn id="dfn-AesCbcParams-iv">iv</dfn>;
};
- </code></pre></div></div>
- </div>
- <div id="aes-cbc-operations" class="section">
- <h4>20.10.4. Operations</h4>
- <dl>
- <dt>Encrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCbcParams">AesCbcParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-cbc-params">AesCbcParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCbcParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
+ </code></pre></div></div>
+ </div>
+ <div id="aes-cbc-operations" class="section">
+ <h4>28.4. Operations</h4>
+ <dl>
+ <dt>Encrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCbcParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>paddedPlaintext</var> be the result of adding padding octets to
+ <var>ciphertext</var> according to the procedure defined in Section 10.3
+ of RFC 2315 [<a href="#RFC2315">RFC2315</a>], step 2, with a value of
+ <var>k</var> of 16.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ciphertext</var> be the result of performing the CBC Encryption
+ operation described in Section 6.2 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCbcParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter and <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>paddedPlaintext</var></a> as the input plaintext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>ciphertext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Decrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCbcParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>paddedPlaintext</var> be the result of performing the CBC Decryption
+ operation described in Section 6.2 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCbcParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter and <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>ciphertext</var></a> as the input ciphertext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>p</var> be the value of the last octet of <var>paddedPlaintext</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>p</var> is zero or greater than 16, or if any of the last <var>p</var>
+ octets of <var>paddedPlaintext</var> have a value which is not <var>p</var>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>plaintext</var> be the result of removing <var>p</var> octets from
+ the end of <var>paddedPlaintext</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>plaintext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not equal to one of
+ 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an AES key of length
+ equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CBC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ to <code>"oct"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128CBC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192CBC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256CBC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
+ object representing an AES key with value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CBC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128CBC"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192CBC"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256CBC"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="aes-cmac" class="section">
+ <h3>29. AES-CMAC</h3>
+ <div id="aes-cmac-description" class="section">
+ <h4>29.1. Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-CMAC"</code> algorithm identifier is used to perform
+ message authentication using AES with a cipher-based MAC, as
+ described in NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>].
+ </p>
+ </div>
+ <div id="aes-cmac-registration" class="section">
+ <h4>29.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-CMAC"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sign</td>
+ <td><a href="#dfn-AesCmacParams">AesCmacParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>verify</td>
+ <td><a href="#dfn-AesCmacParams">AesCmacParams</a></td>
+ <td>boolean</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="aes-cmac-params" class="section">
+ <h4>29.3. AesCmacParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-AesCmacParams">AesCmacParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The length, in bits, of the MAC.</span>
+[EnforceRange] unsigned short <dfn id="dfn-AesCmacParams-length">length</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="aes-cmac-operations" class="section">
+ <h4>29.4. Operations</h4>
+ <dl>
+ <dt>Sign</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>length</var> equal the <a href="#dfn-AesCmacParams-length">length</a>
+ member of <var>normalizedAlgorithm</var>, if present, and 128 otherwise.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>length</var> is zero or greater than 128,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>mac</var> be the result of performing the MAC Generation
+ operation described in Section 6.2 of
+ NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>] using AES as the block
+ cipher, <var>length</var> as the value of the MAC length parameter,
+ <var>Tlen</var>, and <var>message</var> as the message, <var>M</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>mac</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Verify</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>length</var> equal the <a href="#dfn-AesCmacParams-length">length</a>
+ member of <var>normalizedAlgorithm</var>, if present, and 128 otherwise.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>length</var> is zero or greater than 128,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>output</var> be the result of performing the MAC Verification
+ operation described in Section 6.3 of
+ NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>] using AES as the block
+ cipher, <var>length</var> as the value of the MAC length parameter,
+ <var>Tlen</var>, <var>message</var> as the message, <var>M</var> and
+ <var>signature</var> as the received MAC, <var>T'</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return true if <var>output</var> is VALID and false otherwise.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not equal to one of
+ 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not
+ <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an AES key of length
+ equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CMAC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ to <code>"oct"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128CMAC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192CMAC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256CMAC"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
+ object representing an AES key with value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CMAC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128CMAC"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192CMAC"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256CMAC"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If any of the members of
+ <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
+ <var>normalizedDerivedKeyAlgorithm</var>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div id="aes-gcm" class="section">
+ <h3>30. AES-GCM</h3>
+ <div id="aes-gcm-description" class="section">
+ <h4>30.1. Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-GCM"</code> algorithm identifier is used to perform
+ authenticated encryption and decryption using AES in Galois/Counter Mode mode,
+ as described in NIST SP 800-38D [<a href="#SP800-38D">SP800-38D</a>].
+ </p>
+ </div>
+ <div id="aes-gcm-registration" class="section">
+ <h4>30.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-GCM"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>encrypt</td>
+ <td><a href="#dfn-AesGcmParams">AesGcmParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>decrypt</td>
+ <td><a href="#dfn-AesGcmParams">AesGcmParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="aes-gcm-params" class="section">
+ <h4>30.3. AesGcmParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-AesGcmParams">AesGcmParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The initialization vector to use. May be up to 2^64-1 bytes long.</span>
+CryptoOperationData <dfn id="dfn-AesGcmParams-iv">iv</dfn>;
+<span class="comment">// The additional authentication data to include.</span>
+CryptoOperationData? <dfn id="dfn-AesGcmParams-additionalData">additionalData</dfn>;
+<span class="comment">// The desired length of the authentication tag. May be 0 - 128.</span>
+[EnforceRange] octet? <dfn id="dfn-AesGcmParams-tagLength">tagLength</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="aes-gcm-operations" class="section">
+ <h4>30.4. Operations</h4>
+ <dl>
+ <dt>Encrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>plaintext</var> has a length greater than 2^39 - 256
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> has a length greater than 2^64 - 1
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member
+ of <var>normalizedAlgorithm</var> is present, is not null and has a length
+ greater than 2^64 - 1 bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var> is not present or is null:</dt>
+ <dd>Let <var>tagLength</var> be 128.</dd>
+ <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var> is one of 32, 64, 96, 104, 112, 120 or 128:</dt>
+ <dd>Let <var>tagLength</var> be equal to the
+ <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var></dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>paddedPlaintext</var> be the result of adding padding octets to
- <var>ciphertext</var> according to the procedure defined in Section 10.3
- of RFC 2315 [<a href="#RFC2315">RFC2315</a>], step 2, with a value of
- <var>k</var> of 16.
- </p>
- </li>
- <li>
- <p>
- Let <var>ciphertext</var> be the result of performing the CBC Encryption
- operation described in Section 6.2 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCbcParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter and <a href="#concept-contents-of-arraybuffer">the contents of
- <var>paddedPlaintext</var></a> as the input plaintext.
- </p>
- </li>
- <li>
- <p>
- Return <var>ciphertext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Decrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCbcParams">AesCbcParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-cbc-params">AesCbcParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCbcParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>paddedPlaintext</var> be the result of performing the CBC Decryption
- operation described in Section 6.2 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCbcParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter and <a href="#concept-contents-of-arraybuffer">the contents of
- <var>ciphertext</var></a> as the input ciphertext.
- </p>
- </li>
- <li>
- <p>
- Let <var>p</var> be the value of the last octet of <var>paddedPlaintext</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>p</var> is zero or greater than 16, or if any of the last <var>p</var>
- octets of <var>paddedPlaintext</var> have a value which is not <var>p</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>plaintext</var> be the result of removing <var>p</var> octets from
- the end of <var>paddedPlaintext</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>plaintext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>additionalData</var> be <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member of
+ <var>normalizedAlgorithm</var> if present and not null and the empty octet
+ string otherwise.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>C</var> and <var>T</var> be the outputs that result from performing
+ the Authenticated Encryption Function described in Section 7.1 of NIST SP
+ 800-38D [<a href="#SP800-38D">SP800-38D</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesGcmParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter, <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>additionalData</var></a> as the <var>A</var> input parameter,
+ <var>tagLength</var> as the <var>t</var> pre-requisite and <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>plaintext</var></a> as the input plaintext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return a new ArrayBuffer containing <var>C</var> | <var>T</var>
+ where '|' denotes concatenation.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Decrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var> is not present or null:</dt>
+ <dd>Let <var>tagLength</var> be 128.</dd>
+ <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var> is one of 32, 64, 96, 104, 112, 120 or 128:</dt>
+ <dd>Let <var>tagLength</var> be equal to the
+ <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
+ <var>normalizedAlgorithm</var></dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an AES key of length
- equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CBC"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>plaintext</var> has a length less than <var>tagLength</var> bits,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> has a length greater than 2^64 - 1
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member
+ of <var>normalizedAlgorithm</var> is present, is not null and has a length
+ greater than 2^64 - 1
+ bytes,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>tag</var> be the last <var>tagLength</var> bits of
+ <var>ciphertext</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>actualCiphertext</var> be the result of removing the last <var>tagLength</var> bits
+ from <var>ciphertext</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>additionalData</var> be <a href="#concept-contents-of-arraybuffer">the contents</a> of the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member of
+ <var>normalizedAlgorithm</var> if present and not null and the empty octet
+ string otherwise.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the Authenticated Decryption Function described in Section 7.2 of NIST
+ SP 800-38D [<a href="#SP800-38D">SP800-38D</a>] using AES as the block cipher,
+ <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesGcmParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter, <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>additionalData</var></a> as the <var>A</var> input parameter,
+ <var>tagLength</var> as the <var>t</var> pre-requisite, <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>actualCiphertext</var></a> as the input ciphertext, <var>C</var> and <a href="#concept-contents-of-arraybuffer">the contents of <var>tag</var></a> as
+ the authentication tag, <var>T</var>.
+ </p>
+ <dl class="switch">
+ <dt>If the result of the algorithm is the indication of inauthenticity,
+ "<var>FAIL</var>":</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>Let <var>plaintext</var> be the output <var>P</var> of the Authenticated
+ Decryption Function.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return a new ArrayBuffer containing <var>plaintext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not equal to one of
+ 128, 192 or 256,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an AES key of length
+ equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-GCM"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"oct"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128GCM"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192GCM"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256GCM"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
+ object representing an AES key with value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-GCM"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128GCM"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192GCM"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256GCM"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- to <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128CBC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192CBC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256CBC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="aes-cfb" class="section">
+ <h3>31. AES-CFB</h3>
+ <div id="aes-cfb-description" class="section">
+ <h4>31.1. Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-CFB-8"</code> algorithm identifier is used to perform
+ encryption and decryption using AES in Cipher Feedback mode, specifically CFB-8,
+ as described in Section 6.3 of NIST SP 800-38A
+ [<a href="#SP800-38A">SP800-38A</a>].
+ </p>
+ </div>
+ <div id="aes-cfb-registration" class="section">
+ <h4>31.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-CFB-8"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>encrypt</td>
+ <td><a href="#dfn-AesCfbParams">AesCfbParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>decrypt</td>
+ <td><a href="#dfn-AesCfbParams">AesCfbParams</a></td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="aes-cfb-params" class="section">
+ <h4>31.3. AesCfbParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-AesCfbParams">AesCfbParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The initialization vector. <span class="RFC2119">MUST</span> be 16 bytes.</span>
+CryptoOperationData <dfn id="dfn-AesCfbParams-iv">iv</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="aes-cfb-operations" class="section">
+ <h4>31.4. Operations</h4>
+ <dl>
+ <dt>Encrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCfbParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16 bytes, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ciphertext</var> be the result of performing the CFB Encryption
+ operation described in Section 6.3 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCfbParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter, the value 8 as the input parameter
+ <var>s</var>, and <a href="#concept-contents-of-arraybuffer">the contents
+ of<var>plaintext</var></a> as the input plaintext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>ciphertext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Decrypt</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesCfbParams-iv">iv</a> member of
+ <var>normalizedAlgorithm</var> does not have length 16 bytes, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>plaintext</var> be the result of performing the CFB Decryption
+ operation described in Section 6.3 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCfbParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
+ the <var>IV</var> input parameter, the the value 8 as the input parameter
+ <var>s</var>, and <a href="#concept-contents-of-arraybuffer">the contents of
+ <var>ciphertext</var></a> as the input ciphertext.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>plaintext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not equal to one of 128, 192 or 256, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not one of
+ <code>"encrypt"</code>, <code>"decrypt"</code>, <code>"wrapKey"</code> or
+ <code>"unwrapKey"</code>, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate an AES key of length equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CFB-8"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ one of <code>"encrypt"</code>, <code>"decrypt"</code>,
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"oct"</code>,
then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
- object representing an AES key with value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CBC"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128CBC"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192CBC"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256CBC"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="aes-cmac" class="section">
- <h3>20.11. AES-CMAC</h3>
- <div id="aes-cmac-description" class="section">
- <h4>20.11.1. Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"AES-CMAC"</code> algorithm identifier is used to perform
- message authentication using AES with a cipher-based MAC, as
- described in NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>].
- </p>
- </div>
- <div id="aes-cmac-registration" class="section">
- <h4>20.11.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-CMAC"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>sign</td>
- <td><a href="#dfn-AesCmacParams">AesCmacParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>verify</td>
- <td><a href="#dfn-AesCmacParams">AesCmacParams</a></td>
- <td>boolean</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="aes-cmac-params" class="section">
- <h4>20.11.3. AesCmacParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-AesCmacParams">AesCmacParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The length, in bits, of the MAC.</span>
- [EnforceRange] unsigned short <dfn id="dfn-AesCmacParams-length">length</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="aes-cmac-operations" class="section">
- <h4>20.11.4. Operations</h4>
- <dl>
- <dt>Sign</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>length</var> equal the <a href="#dfn-AesCmacParams-length">length</a>
- member of <var>normalizedAlgorithm</var>, if present, and 128 otherwise.
- </p>
- </li>
- <li>
- <p>
- If <var>length</var> is zero or greater than 128,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>mac</var> be the result of performing the MAC Generation
- operation described in Section 6.2 of
- NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>] using AES as the block
- cipher, <var>length</var> as the value of the MAC length parameter,
- <var>Tlen</var>, and <var>message</var> as the message, <var>M</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>mac</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Verify</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCmacParams">AesCmacParams</a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>length</var> equal the <a href="#dfn-AesCmacParams-length">length</a>
- member of <var>normalizedAlgorithm</var>, if present, and 128 otherwise.
- </p>
- </li>
- <li>
- <p>
- If <var>length</var> is zero or greater than 128,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>output</var> be the result of performing the MAC Verification
- operation described in Section 6.3 of
- NIST SP 800-38B [<a href="#SP800-38B">SP800-38B</a>] using AES as the block
- cipher, <var>length</var> as the value of the MAC length parameter,
- <var>Tlen</var>, <var>message</var> as the message, <var>M</var> and
- <var>signature</var> as the received MAC, <var>T'</var>.
- </p>
- </li>
- <li>
- <p>
- Return true if <var>output</var> is VALID and false otherwise.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an AES key of length
- equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CMAC"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128CFB8"</code>,
then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- to <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192CFB8"</code>,
then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128CMAC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192CMAC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256CMAC"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256CFB8"</code>,
then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
- object representing an AES key with value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CMAC"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128CMAC"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192CMAC"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256CMAC"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
- <div id="aes-gcm" class="section">
- <h3>20.12. AES-GCM</h3>
- <div id="aes-gcm-description" class="section">
- <h4>20.12.1. Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"AES-GCM"</code> algorithm identifier is used to perform
- authenticated encryption and decryption using AES in Galois/Counter Mode mode,
- as described in NIST SP 800-38D [<a href="#SP800-38D">SP800-38D</a>].
- </p>
- </div>
- <div id="aes-gcm-registration" class="section">
- <h4>20.12.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-GCM"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>encrypt</td>
- <td><a href="#dfn-AesGcmParams">AesGcmParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>decrypt</td>
- <td><a href="#dfn-AesGcmParams">AesGcmParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="aes-gcm-params" class="section">
- <h4>20.12.3. AesGcmParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-AesGcmParams">AesGcmParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The initialization vector to use. May be up to 2^64-1 bytes long.</span>
- CryptoOperationData <dfn id="dfn-AesGcmParams-iv">iv</dfn>;
- <span class="comment">// The additional authentication data to include.</span>
- CryptoOperationData? <dfn id="dfn-AesGcmParams-additionalData">additionalData</dfn>;
- <span class="comment">// The desired length of the authentication tag. May be 0 - 128.</span>
- [EnforceRange] octet? <dfn id="dfn-AesGcmParams-tagLength">tagLength</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="aes-gcm-operations" class="section">
- <h4>20.12.4. Operations</h4>
- <dl>
- <dt>Encrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesGcmParams">AesGcmParams</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
- <a href="#aes-gcm-params">AesGcmParams</a> is not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>plaintext</var> has a length greater than 2^39 - 256
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> has a length greater than 2^64 - 1
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member
- of <var>normalizedAlgorithm</var> is present, is not null and has a length
- greater than 2^64 - 1 bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var> is not present or is null:</dt>
- <dd>Let <var>tagLength</var> be 128.</dd>
- <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var> is one of 32, 64, 96, 104, 112, 120 or 128:</dt>
- <dd>Let <var>tagLength</var> be equal to the
- <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var></dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>additionalData</var> be <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member of
- <var>normalizedAlgorithm</var> if present and not null and the empty octet
- string otherwise.
- </p>
- </li>
- <li>
- <p>
- Let <var>C</var> and <var>T</var> be the outputs that result from performing
- the Authenticated Encryption Function described in Section 7.1 of NIST SP
- 800-38D [<a href="#SP800-38D">SP800-38D</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesGcmParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter, <a href="#concept-contents-of-arraybuffer">the contents of
- <var>additionalData</var></a> as the <var>A</var> input parameter,
- <var>tagLength</var> as the <var>t</var> pre-requisite and <a href="#concept-contents-of-arraybuffer">the contents of
- <var>plaintext</var></a> as the input plaintext.
- </p>
- </li>
- <li>
- <p>
- Return a new ArrayBuffer containing <var>C</var> | <var>T</var>
- where '|' denotes concatenation.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Decrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesGcmParams">AesGcmParams</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
- <a href="#aes-gcm-params">AesGcmParams</a> is not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var> is not present or null:</dt>
- <dd>Let <var>tagLength</var> be 128.</dd>
- <dt>If the <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var> is one of 32, 64, 96, 104, 112, 120 or 128:</dt>
- <dd>Let <var>tagLength</var> be equal to the
- <a href="#dfn-AesGcmParams-tagLength">tagLength</a> member of
- <var>normalizedAlgorithm</var></dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>plaintext</var> has a length less than <var>tagLength</var> bits,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> has a length greater than 2^64 - 1
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member
- of <var>normalizedAlgorithm</var> is present, is not null and has a length
- greater than 2^64 - 1
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>tag</var> be the last <var>tagLength</var> bits of
- <var>ciphertext</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>actualCiphertext</var> be the result of removing the last <var>tagLength</var> bits
- from <var>ciphertext</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>additionalData</var> be <a href="#concept-contents-of-arraybuffer">the contents</a> of the <a href="#dfn-AesGcmParams-additionalData">additionalData</a> member of
- <var>normalizedAlgorithm</var> if present and not null and the empty octet
- string otherwise.
- </p>
- </li>
- <li>
- <p>
- Perform the Authenticated Decryption Function described in Section 7.2 of NIST
- SP 800-38D [<a href="#SP800-38D">SP800-38D</a>] using AES as the block cipher,
- <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesGcmParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter, <a href="#concept-contents-of-arraybuffer">the contents of
- <var>additionalData</var></a> as the <var>A</var> input parameter,
- <var>tagLength</var> as the <var>t</var> pre-requisite, <a href="#concept-contents-of-arraybuffer">the contents of
- <var>actualCiphertext</var></a> as the input ciphertext, <var>C</var> and <a href="#concept-contents-of-arraybuffer">the contents of <var>tag</var></a> as
- the authentication tag, <var>T</var>.
- </p>
- <dl class="switch">
- <dt>If the result of the algorithm is the indication of inauthenticity,
- "<var>FAIL</var>":</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>
- </dd>
- <dt>Otherwise:</dt>
- <dd>Let <var>plaintext</var> be the output <var>P</var> of the Authenticated
- Decryption Function.</dd>
- </dl>
- </li>
- <li>
- <p>
- Return a new ArrayBuffer containing <var>plaintext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an AES key of length
- equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-GCM"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128GCM"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192GCM"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256GCM"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
- object representing an AES key with value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-GCM"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128GCM"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192GCM"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256GCM"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
+ object representing an AES key with value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-CFB-8"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128CFB8"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192CFB8"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256CFB8"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> property of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> property of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="aes-kw" class="section">
+ <h3>32. AES-KW</h3>
+ <div id="aes-kw-description" class="section">
+ <h4>32.1. Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"AES-KW"</code> algorithm identifier is used to perform
+ key wrapping using AES, as
+ described in [<a href="#rfc3394">RFC3394</a>].
+ </p>
+ </div>
+ <div id="aes-kw-registration" class="section">
+ <h4>32.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"AES-KW"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>wrapKey</td>
+ <td>None</td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>unwrapKey</td>
+ <td>None</td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="aes-kw-operations" class="section">
+ <h4>32.3. Operations</h4>
+ <dl>
+ <dt>Wrap Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>plaintext</var> is not a multiple of 64 bits in length,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>ciphertext</var> be the result of performing the Key Wrap
+ operation described in Section 2.2.1 of [<a href="#rfc3394">RFC3394</a>]
+ with <var>plaintext</var> as the plaintext to be wrapped and using the default
+ Initial Value defined in Section 2.2.3.1 of the same document.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>ciphertext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Unwrap Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>plaintext</var> be the result of performing the Key Unwrap
+ operation described in Section 2.2.2 of [<a href="#rfc3394">RFC3394</a>] with
+ <var>ciphertext</var> as the input ciphertext and using the default Initial
+ Value defined in Section 2.2.3.1 of the same document.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the Key Unwrap operation returns an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>plaintext</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesKeyGenParams-length">length</a> property of
+ <var>normalizedAlgorithm</var> is not equal to one of 128, 192 or 256, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not one of
+ <code>"wrapKey"</code> or <code>"unwrapKey"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated AES key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-KW"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to equal the
+ <a href="#dfn-AesKeyGenParams-length">length</a> property of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ one of <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
+
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the length in bits of <var>data</var> is not 128, 192 or 256
+
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"oct"</code>,
then <a href="#concept-return-an-error">return an error</a> named
<a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>data</var> has length 128 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A128KW"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 192 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A192KW"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>If <var>data</var> has length 256 bits:</dt>
+ <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
+ not <code>"A256KW"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"enc"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>. </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
+ object representing an AES key with value <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"AES-KW"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to the length, in bits, of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 128:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A128KW"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 192:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A192KW"</code>.</dd>
+ <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
+ <var>key</var> is 256:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"A256KW"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+
+ <div id="hmac" class="section">
+ <h3>33. HMAC</h3>
+ <div id="hmac-description" class="section">
+ <h4>33.1. Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>HMAC</code> algorithm calculates and verifies hash-based message
+ authentication codes according to [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>].
+ </p>
+ </div>
+ <div id="hmac-registration" class="section">
+ <h4>33.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"HMAC"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sign</td>
+ <td>None</td>
+ <td>ArrayBuffer</td>
+ </tr>
+ <tr>
+ <td>verify</td>
+ <td>None</td>
+ <td>boolean</td>
+ </tr>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-HmacKeyGenParams">HmacKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-HmacImportParams">HmacImportParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ <tr>
+ <td>get key length</td>
+ <td><a href="#dfn-HmacDerivedKeyParams">HmacDerivedKeyParams</a></td>
+ <td>Integer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="hmac-importparams" class="section">
+ <h4>33.3. HmacImportParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-HmacImportParams">HmacImportParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The inner hash function to use.</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-HmacImportParams-hash">hash</dfn>;
+<span class="comment">// The length (in bits) of the key.</span>
+[EnforceRange] unsigned long <dfn id="dfn-HmacImportParams-length">length</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="HmacKeyAlgorithm-dictionary" class="section">
+ <h4>33.4. HmacKeyAlgorithm dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
+<span class="comment">// The inner hash function to use.</span>
+KeyAlgorithm <dfn id="dfn-HmacKeyAlgorithm-hash">hash</dfn>;
+<span class="comment">// The length (in bits) of the key.</span>
+unsigned long <dfn id="dfn-HmacKeyAlgorithm-length">length</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="hmac-keygen-params" class="section">
+ <h4>33.5. HmacKeyGenParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-HmacKeyGenParams">HmacKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The inner hash function to use.</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-HmacKeyGenParams-hash">hash</dfn>;
+<span class="comment">// The length (in bits) of the key to generate. If unspecified, the
+// recommended length will be used, which is the size of the associated hash function's block
+// size.</span>
+[EnforceRange] unsigned long <dfn id="dfn-HmacKeyGenParams-length">length</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="hmac-derivedkey-params" class="section">
+ <h4>33.6. HmacDerivedKeyParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-HmacDerivedKeyParams">HmacDerivedKeyParams</dfn> : <a href="#dfn-HmacImportParams">HmacImportParams</a> {
+<span class="comment">// The length (in bits) of the key to generate. If unspecified, the
+// recommended length will be used, which is the size of the associated hash function's block
+// size.</span>
+[EnforceRange] unsigned long <dfn id="dfn-HmacDerivedKeyParams-length">length</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="hmac-operations" class="section">
+ <h4>33.7. Operations</h4>
+ <dl>
+ <dt>Sign</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>mac</var> be the result of performing the MAC Generation operation
+ described in Section 4 of [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using
+ the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
+ internal slot of <var>key</var>, the hash function identified by the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> and <var>message</var> as the input data <var>text</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>mac</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Verify</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>mac</var> be the result of performing the MAC Generation operation
+ described in Section 4 of [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using
+ the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
+ internal slot of <var>key</var>, the hash function identified by the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var> and <var>message</var> as the input data <var>text</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return true if <var>mac</var> is equal to <var>signature</var> and false
+ otherwise.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacKeyGenParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is not present:
+ </dt>
+ <dd>
+ Let <var>length</var> be the block size in bits of the hash function
+ identified by the <a href="#dfn-HmacKeyGenParams-hash">hash</a> member
+ of <var>normalizedAlgorithm</var>.
+ </dd>
+ <dt>
+ Otherwise, if the <a href="#dfn-HmacKeyGenParams-length">length</a>
+ member of <var>normalizedAlgorithm</var> is non-zero:
+ </dt>
+ <dd>
+ Let <var>length</var> be equal to the
+ <a href="#dfn-HmacKeyGenParams-length">length</a>
+ member of <var>normalizedAlgorithm</var>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any entry which is not <code>"sign"</code> or
+ <code>"verify"</code>, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate a key of length <var>length</var> bits.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key generation step fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new
+ <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
+ generated key.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"HMAC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a new
+ <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to equal the <a href="#dfn-Algorithm-name">name</a>
+ member of the <a href="#dfn-HmacKeyGenParams-hash">hash</a>
+ member of <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute
+ of <var>algorithm</var> to <var>hash</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to be <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains an entry which is not
+ <code>"sign"</code> or <code>"verify"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string contained in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var> is present and has a
+ <a href="#dfn-Algorithm-name">name</a> member:
+ </dt>
+ <dd>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to equal the <a href="#dfn-Algorithm-name">name</a>
+ member of the <a href="#dfn-HmacImportParams-hash">hash</a>
+ member of <var>normalizedAlgorithm</var>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary represented by <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"kty"</code> field of <var>jwk</var> is not
+ <code>"oct"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>jwk</var> does not meet the requirements of
+ Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the octet string obtained by decoding the
+ <code>"k"</code> field of <var>jwk</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var> is present and has a
+ <a href="#dfn-Algorithm-name">name</a> member:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to equal the <a href="#dfn-Algorithm-name">name</a> member of the <a href="#dfn-HmacImportParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is
+ <code>"SHA-1"</code>:
+ </dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present
+ and is not <code>"HS1"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is
+ <code>"SHA-256"</code>:
+ </dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present
+ and is not <code>"HS256"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is
+ <code>"SHA-384"</code>:
+ </dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present
+ and is not <code>"HS384"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is
+ <code>"SHA-512"</code>:
+ </dt>
+ <dd>
+ If the <code>"alg"</code> field of <var>jwk</var> is present
+ and is not <code>"HS512"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the <code>alg</code> field of <var>jwk</var> is not present,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is
+ <code>"HS1"</code>:
+ </dt>
+ <dd>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to <code>"SHA-1"</code>.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is
+ to <code>"HS256"</code>:
+ </dt>
+ <dd>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to <code>"SHA-256"</code>.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is
+ <code>"HS384"</code>:
+ </dt>
+ <dd>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to <code>"SHA-384"</code>.
+ </dd>
+ <dt>
+ If the <code>"alg"</code> field of <var>jwk</var> is
+ <code>"HS512"</code>:
+ </dt>
+ <dd>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> to <code>"SHA-512"</code>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If the <code>"use"</code> field of <var>jwk</var> is present, and is
+ not <code>"sign"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
+ is invalid according to the requirements of
+ <a href="#jwk">JSON Web Key</a> or
+ does not contain all of the specified <var>usages</var> values,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>"ext"</code> field of <var>jwk</var> is present and
+ has the value false and <var>extractable</var> is true,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>length</var> be equivalent to the length, in octets, of
+ <var>data</var>, multiplied by 8.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>length</var> is zero
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacImportParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is present:
+ </dt>
+ <dd>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacImportParams-length">length</a> member of
+ <var>normalizedAlgorithm</var> is greater than <var>length</var>:
+ </dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-HmacImportParams-length">length</a> member of
+ <var>normalizedAlgorithm</var>, is less than or equal to
+ <var>length</var> minus eight:
+ </dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>
+ Otherwise:
+ </dt>
+ <dd>
+ Set <var>length</var> equal to the <a href="#dfn-HmacImportParams-length">
+ length</a> member of <var>normalizedAlgorithm</var>.
+ </dd>
+ </dl>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
+ object representing an HMAC key with the first <var>length</var>
+ bits of <var>data</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"HMAC"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-HmacKeyAlgorithm-length">length</a> attribute of
+ <var>algorithm</var> to <var>length</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of
+ <var>algorithm</var> to <var>hash</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>If <var>format</var> is <code>"raw"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>kty</code> attribute of <var>jwk</var> to the
+ string <code>"oct"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>k</code> attribute of <var>jwk</var> to be a string
+ containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>hash</var> be the
+ <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of
+ <var>algorithm</var>.
+ </p>
+ </li>
+
+ <li>
+ <dl class="switch">
+ <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is <code>"SHA-1"</code>:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"HS1"</code>.</dd>
+ <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is <code>"SHA-256"</code>:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"HS256"</code>.</dd>
+ <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is <code>"SHA-384"</code>:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"HS384"</code>.</dd>
+ <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>hash</var> is <code>"SHA-512"</code>:</dt>
+ <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
+ the string <code>"HS512"</code>.</dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
+ <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of converting <var>jwk</var>
+ to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get key length</dt>
+ <dd>
+ <ol>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-HmacDerivedKeyParams-length">length</a> member of
+ <var>normalizedDerivedKeyAlgorithm</var> is not present:
+ </dt>
+ <dd>
+ Let <var>length</var> be the block size in bytes of the hash function
+ identified by the <a href="#dfn-HmacImportParams-hash">hash</a> member
+ of <var>normalizedDerivedKeyAlgorithm</var>.
+ </dd>
+ <dt>
+ Otherwise, if the <a href="#dfn-HmacDerivedKeyParams-length">length</a>
+ member of <var>normalizedDerivedKeyAlgorithm</var> is non-zero:
+ </dt>
+ <dd>
+ Let <var>length</var> be equal to the
+ <a href="#dfn-HmacDerivedKeyParams-length">length</a>
+ member of <var>normalizedDerivedKeyAlgorithm</var>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>length</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div id="dh" class="section">
+ <h3>34. Diffie-Hellman</h3>
+ <div id="dh-description" class="section">
+ <h4>34.1. Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ This describes using Diffie-Hellman for key generation and key agreement, as specified
+ by <a href="#PKCS3">PKCS #3</a>.
+ </p>
+ </div>
+ <div id="dh-registration" class="section">
+ <h4>34.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"DH"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>generateKey</td>
+ <td><a href="#dfn-DhKeyGenParams">DhKeyGenParams</a></td>
+ <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
+ </tr>
+ <tr>
+ <td>deriveBits</td>
+ <td><a href="#dfn-DhKeyDeriveParams">DhKeyDeriveParams</a></td>
+ <td>Octet string</td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td><a href="#dfn-DhImportKeyParams">DhImportKeyParams</a></td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>exportKey</td>
+ <td>None</td>
+ <td>object</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="dh-DhKeyGenParams" class="section">
+ <h4>34.3. DhKeyGenParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-DhKeyGenParams">DhKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The prime p.</span>
+BigInteger <dfn id="dfn-DhKeyGenParams-prime">prime</dfn>;
+<span class="comment">// The base g.</span>
+BigInteger <dfn id="dfn-DhKeyGenParams-generator">generator</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="dh-DhKeyAlgorithm" class="section">
+ <h4>34.4. DhKeyAlgorithm dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-DhKeyAlgorithm">DhKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
+<span class="comment">// The prime p.</span>
+BigInteger <dfn id="dfn-DhKeyAlgorithm-prime">prime</dfn>;
+<span class="comment">// The base g.</span>
+BigInteger <dfn id="dfn-DhKeyAlgorithm-generator">generator</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="dh-DhKeyDeriveParams" class="section">
+ <h4>34.5. DhKeyDeriveParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-DhKeyDeriveParams">DhKeyDeriveParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The peer's public value.</span>
+<a href="#dfn-CryptoKey">CryptoKey</a> <dfn id="dfn-DhKeyDeriveParams-public">public</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="dh-DhImportKeyParams" class="section">
+ <h4>34.6. DhImportKeyParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-DhImportKeyParams">DhImportKeyParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The prime p.</span>
+BigInteger <dfn id="dfn-DhImportKeyParams-prime">prime</dfn>;
+<span class="comment">// The base g.</span>
+BigInteger <dfn id="dfn-DhImportKeyParams-generator">generator</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="dh-operations" class="section">
+ <h4>34.7. Operations</h4>
+ <dl>
+ <dt>Generate Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains a value which is not
+ one of <code>"deriveKey"</code> or <code>"deriveBits"</code>,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate a Diffie-Hellman key pair, as defined in Section 7 of
+ [<a href="#PKCS3">PKCS #3</a>], with prime, <var>p</var>, and base,
+ <var>g</var>, as specified in the
+ <a href="#dfn-DhKeyGenParams-prime">prime</a> and
+ <a href="#dfn-DhKeyGenParams-generator">generator</a> properties of
+ <var>normalizedAlgorithm</var>, respectively.
+ </p>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>algorithm</var> to <code>"DH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-DhKeyGenParams-prime">prime</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a>
+ attribute of <var>algorithm</var> to equal the
+ <a href="#dfn-DhKeyGenParams-generator">generator</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the public key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> to <code>"public"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>publicKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>publicKey</var> to true.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>publicKey</var> to be the empty list.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the private key of the generated key pair.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>privateKey</var> to <code>"private"</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>privateKey</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>privateKey</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>privateKey</var> to be <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
+ dictionary.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
+ of <var>result</var> to be <var>publicKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
+ of <var>result</var> to be <var>privateKey</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return the result of converting <var>result</var> to an ECMAScript Object, as
+ defined by [<a href="#WebIDL">WEBIDL</a>].
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Derive Bits</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>publicKey</var> be the
+ <a href="#dfn-DhKeyDeriveParams-public">public</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> is not <code>"DH"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>publicKey</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> is not equal to the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
+ named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of the
+ [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>publicKey</var> is not equal to the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
+ <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
+ named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Perform the Diffie-Hellman Phase II algorithm as specified in Section 8 of [<a href="#PKCS3">PKCS #3</a>] with <var>key</var> as the DH private value
+ <var>x</var> and the Diffie-Hellman public value represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of the <a href="#dfn-DhKeyDeriveParams-public">public</a> member of
+ <var>normalizedAlgorithm</var> as the other's public value <var>PV'</var>.
+ </p>
+ <dl class="switch">
+ <dt>If performing the operation results in an error:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ Let <var>secret</var> be the output of the DH Phase II, <var>SK</var>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the length of <var>secret</var> in bits is less than
+ <var>length</var>:
+ </dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>Return the first <var>length</var> bits of <var>secret</var>.</dd>
+ </dl>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import Key</dt>
+ <dd>
+ <dl class="switch">
+ <dt>
+ If <var>format</var> is <code>"raw"</code>:
+ </dt>
+ <dd>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div>
<p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var>.
+ Raw import of private values is presently not supported.
</p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="aes-cfb" class="section">
- <h3>20.13. AES-CFB</h3>
- <div id="aes-cfb-description" class="section">
- <h4>20.13.1. Description</h4>
- <p class="norm">This section is non-normative.</p>
+ </div>
+ <ol>
+ <li>
+ <p>
+ If <var>extractable</var> is false,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>PV</var> be the integer which results from interpreting the
+ octets of <var>keyData</var> as an unsigned big integer with most
+ significant octet first.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing a Diffie-Hellman public key with public value <var>PV</var>
+ and with prime, <var>p</var> and base, <var>g</var> equal to the <a href="#dfn-DhImportKeyParams-prime">prime</a> and <a href="#dfn-DhImportKeyParams-generator">generator</a> properties of
+ <var>normalizedAlgorithm</var> respectively.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"public"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-Algorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"DH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
+ <var>algorithm</var> to equal the <a href="#dfn-DhImportKeyParams-prime">prime</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
+ <var>algorithm</var> to equal the <a href="#dfn-DhImportKeyParams-generator">generator</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
+ of <var>key</var> to <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ If <var>format</var> is <code>"spki"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>spki</var> be the result of running the <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a> algorithm
+ over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is not
+ equivalent to the <code>dhKeyAgreement</code> OID defined in Section 9 of
+ [<a href="#PKCS3">PKCS #3</a>], then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the <code>algorithm</code>
+ AlgorithmIdentifier field of <var>spki</var> is absent, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not an instance of the <code>DHParameter</code>
+ ASN.1 type defined in Section 9 of <a href="#PKCS3">PKCS #3</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the Diffie-Hellman public key obtained by parsing the
+ <code>subjectPublicKey</code> field of <var>spki</var> as an ASN.1
+ INTEGER.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"public"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>algorithm</var> to <code>"DH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
+ <var>algorithm</var> to a new <code>BigInteger</code> equal to the
+ octet string encoding of the <code>prime</code> field of
+ <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
+ <var>algorithm</var> to a new <code>BigInteger</code> equal to the
+ octet string encoding of the <code>base</code> field of
+ <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
+ of <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ If <var>format</var> is <code>"pkcs8"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains a value which is not one of
+ <code>"deriveKey"</code> or <code>"deriveBits"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>privateKeyInfo</var> be the result of running the
+ <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
+ algorithm over <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If an error occurred while parsing, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>algorithm</code> object identifier field of the
+ <code>algorithm</code> AlgorithmIdentifier field of
+ <var>privateKeyInfo</var> is not equivalent to the
+ <code>dhKeyAgreement</code> OID defined in Section 9 of [<a href="#PKCS3">PKCS #3</a>], then <a href="#concept-return-an-error">return
+ an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field of
+ <var>privateKeyInfo</var> is absent, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>params</var> be the <code>parameters</code> field of the
+ <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field of
+ <var>privateKeyInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>params</var> is not an instance of the <code>DHParameter</code>
+ ASN.1 type defined in Section 9 of <a href="#PKCS3">PKCS #3</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the Diffie-Hellman private key obtained by parsing the
+ <code>privateKey</code> field of <var>privateKeyInfo</var> as an ASN.1
+ INTEGER.
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"private"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>algorithm</var> to <code>"DH"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
+ <var>algorithm</var> to a new <code>BigInteger</code> equal to the
+ octet string encoding of the <code>prime</code> field of
+ <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
+ <var>algorithm</var> to a new <code>BigInteger</code> equal to the
+ octet string encoding of the <code>base</code> field of
+ <var>params</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
+ of <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </dd>
+ <dt>Export Key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ cannot be accessed, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <dl class="switch">
+ <dt>
+ If <var>format</var> is <code>"raw"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is <code>"public"</code>:
+ </dt>
+ <dd>
+ Let <var>data</var> be the Public Value, <var>PV</var>, associated
+ with <var>key</var> as specified in Section 7 of [<a href="#PKCS3">PKCS #3</a>].
+ </dd>
+ <dt>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is <code>"private"</code>:
+ </dt>
+ <dd>
+ Let <var>data</var> be the octet string that represents the private
+ value <var>x</var> associated with <var>key</var> as a big integer,
+ most significant octet first.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ If <var>format</var> is <code>"spki"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a href="#concept-encode-a-subjectPublicKeyInfo">encoding a
+ subjectPublicKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithmIdentifier</var> field to an
+ <code>AlgorithmIdentifier</code> ASN.1 structure with the
+ following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the
+ <code>dhKeyAgreement</code> OID defined in Section 9 of <a href="#PKCS3">PKCS #3</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>DHParams</code> ASN.1 structure defined in Section 9 of
+ <a href="#PKCS3">PKCS #3</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>prime</var> field to an ASN.1 INTEGER that is
+ equivalent to the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>base</var> field to an ASN.1 INTEGER that is
+ equivalent to the <a href="#dfn-DhKeyAlgorithm-generator">generator</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>subjectPublicKey</var> to an ASN.1 INTEGER that
+ corresponds to the Diffie-Hellman public value represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
+ <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ If <var>format</var> is <code>"pkcs8"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
+ of <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>data</var> be the result of <a href="#concept-encode-a-privateKeyInfo">encoding a
+ privateKeyInfo</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>privateKeyAlgorithm</var> field to a
+ <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 structure with
+ the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>algorithm</var> field to the
+ <code>dhKeyAgreement</code> OID defined in Section 9 of <a href="#PKCS3">PKCS #3</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>parameters</var> field to an instance of the
+ <code>DHParams</code> ASN.1 structure defined in Section 9 of
+ <a href="#PKCS3">PKCS #3</a> with the following properties:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Set the <var>prime</var> field to an ASN.1 INTEGER that is
+ equivalent to the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
+ the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <var>base</var> field to an ASN.1 INTEGER that is
+ equivalent to the <a href="#dfn-DhKeyAlgorithm-generator">generator</a>
+ attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
+ internal slot of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Set the <var>privateKey</var> field to an ASN.1 INTEGER that
+ corresponds to the Diffie-Hellman private value represented by
+ [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
+ of <var>key</var>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be a new <code>ArrayBuffer</code> containing
+ <var>data</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div id="sha" class="section">
+ <h3>35. SHA</h3>
+ <div id="sha-description" class="section">
+ <h4>35.1. Description</h4>
+ <p>
+ This describes the SHA-1 and SHA-2 families, as specified by
+ [<a href="#FIPS180-4">FIPS PUB 180-4</a>].
+ </p>
+ </div>
+ <div id="sha-registration" class="section">
+ <h4>35.2. Registration</h4>
+ <p>
+ The following algorithms are added as <a href="#recognized-algorithm-name">
+ recognized algorithm names</a>:
+ </p>
+ <dl>
+ <dt id="alg-sha-1"><code>"SHA-1"</code></dt>
+ <dd>The SHA-1 algorithm as specified in Section 6.1</dd>
+ <dt id="alg-sha-256"><code>"SHA-256"</code></dt>
+ <dd>The SHA-256 algorithm as specified in Section 6.2</dd>
+ <dt id="alg-sha-384"><code>"SHA-384"</code></dt>
+ <dd>The SHA-384 algorithm as specified in Section 6.5</dd>
+ <dt id="alg-sha-512"><code>"SHA-512"</code></dt>
+ <dd>The SHA-512 algorithm as specified in Section 6.4</dd>
+ </dl>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>digest</td>
+ <td>None</td>
+ <td>ArrayBuffer</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="sha-operations" class="section">
+ <h4>35.3. Operations</h4>
+ <dl>
+ <dt>Digest</dt>
+ <dd>
+ <ol>
+ <li>
+ <dl class="switch">
+ <dt>
+ If the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>normalizedAlgorithm</var> is a cases-sensitive string match for
+ <code>"SHA-1"</code>:
+ </dt>
+ <dd>
+ Let <var>result</var> be the result of performing the SHA-1 hash function
+ defined in Section 6.1 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
+ <var>message</var> as the input message, <var>M</var>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>normalizedAlgorithm</var> is a cases-sensitive string match for
+ <code>"SHA-256"</code>:
+ </dt>
+ <dd>
+ Let <var>result</var> be the result of performing the SHA-256 hash function
+ defined in Section 6.2 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
+ <var>message</var> as the input message, <var>M</var>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>normalizedAlgorithm</var> is a cases-sensitive string match for
+ <code>"SHA-384"</code>:
+ </dt>
+ <dd>
+ Let <var>result</var> be the result of performing the SHA-384 hash function
+ defined in Section 6.5 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
+ <var>message</var> as the input message, <var>M</var>.
+ </dd>
+ <dt>
+ If the <a href="#dfn-Algorithm-name">name</a> member of
+ <var>normalizedAlgorithm</var> is a cases-sensitive string match for
+ <code>"SHA-512"</code>:
+ </dt>
+ <dd>
+ Let <var>result</var> be the result of performing the SHA-1 hash function
+ defined in Section 6.4 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
+ <var>message</var> as the input message, <var>M</var>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ <p>
+ If performing the operation results in an error, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return a new ArrayBuffer containing <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div id="concatkdf" class="section">
+ <h3>36. Concat KDF</h3>
+ <div id="concatkdf-description" class="section">
+ <h4>36.1. Description</h4>
+ <p>
+ The <code>"CONCAT"</code> algorithm identifier is used to perform key derivation
+ using the key derivation algorithm defined in Section 5.8.1 of NIST SP 800-56A
+ [<a href="#SP800-56A">SP800-56A</a>].
+ </p>
+ </div>
+ <div id="concatkdf-registration" class="section">
+ <h4>36.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"CONCAT"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>deriveBits</td>
+ <td><a href="#dfn-ConcatParams">ConcatParams</a></td>
+ <td>Octet string</td>
+ </tr>
+ <tr>
+ <td>Import key</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>Get key length</td>
+ <td>None</td>
+ <td>Integer or null</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="concat-params" class="section">
+ <h4>36.3. ConcatParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-ConcatParams">ConcatParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The digest method to use to derive the keying material.</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-ConcatParams-hash">hash</dfn>;
+
+<span class="comment">// A bit string corresponding to the AlgorithmId field of the OtherInfo parameter.</span>
+<span class="comment">// The AlgorithmId indicates how the derived keying material will be parsed and for which</span>
+<span class="comment">// algorithm(s) the derived secret keying material will be used.</span>
+CryptoOperationData <dfn id="dfn-ConcatParams-algorithmId">algorithmId</dfn>;
+<span class="comment">// A bit string that corresponds to the PartyUInfo field of the OtherInfo parameter.</span>
+CryptoOperationData <dfn id="dfn-ConcatParams-partyUInfo">partyUInfo</dfn>;
+<span class="comment">// A bit string that corresponds to the PartyVInfo field of the OtherInfo parameter.</span>
+CryptoOperationData <dfn id="dfn-ConcatParams-partyVInfo">partyVInfo</dfn>;
+<span class="comment">// An optional bit string that corresponds to the SuppPubInfo field of the OtherInfo parameter.</span>
+CryptoOperationData? <dfn id="dfn-ConcatParams-publicInfo">publicInfo</dfn>;
+<span class="comment">// An optional bit string that corresponds to the SuppPrivInfo field of the OtherInfo parameter.</span>
+CryptoOperationData? <dfn id="dfn-ConcatParams-privateInfo">privateInfo</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="concat-operations" class="section">
+ <h4>36.4. Operations</h4>
+ <dl>
+ <dt>Derive Bits</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Let <var>secret</var> be the result of performing the Concatenation Key
+ Derivation Function defined in Section 5.8.1 of
+ [<a href="#SP800-56A">SP800-56A</a>] with <var>length</var> as
+ <var>keydatalen</var>, the hash function identified by the
+ <a href="#dfn-ConcatParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var> as <var>H</var>, the
+ <a href="#dfn-ConcatParams-algorithmId">algorithmId</a> member of
+ <var>normalizedAlgorithm</var> as <var>AlgorithmID</var>, the
+ <a href="#dfn-ConcatParams-partyUInfo">partyUInfo</a> member of
+ <var>normalizedAlgorithm</var> as <var>PartyUInfo</var>, the
+ <a href="#dfn-ConcatParams-partyVInfo">partyVInfo</a> member of
+ <var>normalizedAlgorithm</var> as <var>PartyVInfo</var>, the
+ <a href="#dfn-ConcatParams-publicInfo">publicInfo</a> member of
+ <var>normalizedAlgorithm</var>, if present and not null, as
+ <var>publicInfo</var> and the
+ <a href="#dfn-ConcatParams-privateInfo">privateInfo</a> member of
+ <var>normalizedAlgorithm</var>, if present and not null, as
+ <var>privateInfo</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the operation fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>secret</var>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import key</dt>
+ <dd>
+ <dl class="switch">
+ <dt>
+ If <var>format</var> is <code>"raw"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains a value that is not
+ <code>"deriveKey"</code> or <code>"deriveBits"</code>,
+
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the key data provided in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"secret"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"CONCAT"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
+ of <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </dd>
+ <dt>Get length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Return null.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div id="hkdf-ctr" class="section">
+ <h3>37. HKDF-CTR</h3>
+ <div id="hkdf-ctr-description" class="section">
+ <h4>37.1. Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"HKDF-CTR"</code> algorithm identifier is used to
+ perform key derivation using the extraction-then-expansion approach described in
+ NIST SP 800-56C[<a href="#SP800-56C">SP800-56C</a>], using HMAC in counter mode,
+ as described in Section 5.1 of NIST SP 800-108
+ [<a href="#SP800-108">SP800-108</a>].
+ </p>
+ </div>
+ <div id="hkdf-ctr-registration" class="section">
+ <h4>37.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a>
+ for this algorithm is <code>"HKDF-CTR"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>deriveBits</td>
+ <td><a href="#dfn-HkdfCtrParams">HkdfCtrParams</a></td>
+ <td><a href="#dfn-ArrayBuffer">ArrayBuffer</a></td>
+ </tr>
+ <tr>
+ <td>Import key</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>Get key length</td>
+ <td>None</td>
+ <td>Integer or null</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="hkdf-ctr-params" class="section">
+ <h4>37.3. HkdfCtrParams dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-HkdfCtrParams">HkdfCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+<span class="comment">// The algorithm to use with HMAC (e.g.: <a href="#sha-256">SHA-256</a>)</span>
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-HkdfCtrParams-hash">hash</dfn>;
+<span class="comment">// A bit string that corresponds to the label that identifies the purpose for the derived keying material.</span>
+CryptoOperationData <dfn id="dfn-HkdfCtrParams-label">label</dfn>;
+<span class="comment">// A bit string that corresponds to the context of the key derivation, as described in Section 5 of NIST SP 800-108 [<a href="#SP800-108">SP800-108</a>]</span>
+CryptoOperationData <dfn id="dfn-HkdfCtrParams-context">context</dfn>;
+};
+ </code></pre></div></div>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div>
<p>
- The <code>"AES-CFB-8"</code> algorithm identifier is used to perform
- encryption and decryption using AES in Cipher Feedback mode, specifically CFB-8,
- as described in Section 6.3 of NIST SP 800-38A
- [<a href="#SP800-38A">SP800-38A</a>].
+ The definition of HKDF allows the caller to supply an optional pseudorandom salt
+ value, which is used as the key during the extract phase. If this value is not
+ supplied, an all zero string is used instead. However, support for an explicit
+ salt value is not widely implemented in existing APIs, nor is it required by
+ existing usages of HKDF. Should this be an optional parameter, and if so, what
+ should the behavior be of a user agent that does not support explicit salt
+ values (is it conforming or non-conforming?)
</p>
</div>
- <div id="aes-cfb-registration" class="section">
- <h4>20.13.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-CFB-8"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>encrypt</td>
- <td><a href="#dfn-AesCfbParams">AesCfbParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>decrypt</td>
- <td><a href="#dfn-AesCfbParams">AesCfbParams</a></td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="aes-cfb-params" class="section">
- <h4>20.13.3. AesCfbParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-AesCfbParams">AesCfbParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The initialization vector. <span class="RFC2119">MUST</span> be 16 bytes.</span>
- CryptoOperationData <dfn id="dfn-AesCfbParams-iv">iv</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="aes-cfb-operations" class="section">
- <h4>20.13.4. Operations</h4>
- <dl>
- <dt>Encrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCfbParams">AesCfbParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-cfb-params">AesCfbParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCfbParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ciphertext</var> be the result of performing the CFB Encryption
- operation described in Section 6.3 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCfbParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter, the value 8 as the input parameter
- <var>s</var>, and <a href="#concept-contents-of-arraybuffer">the contents
- of<var>plaintext</var></a> as the input plaintext.
- </p>
- </li>
- <li>
- <p>
- Return <var>ciphertext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Decrypt</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesCfbParams">AesCfbParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-cfb-params">AesCfbParams</a> are not
- present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesCfbParams-iv">iv</a> member of
- <var>normalizedAlgorithm</var> does not have length 16
- bytes,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>plaintext</var> be the result of performing the CFB Decryption
- operation described in Section 6.3 of NIST SP 800-38A [<a href="#SP800-38A">SP800-38A</a>] using AES as the block cipher, <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-AesCfbParams-iv">iv</a> member of <var>normalizedAlgorithm</var> as
- the <var>IV</var> input parameter, the the value 8 as the input parameter
- <var>s</var>, and <a href="#concept-contents-of-arraybuffer">the contents of
- <var>ciphertext</var></a> as the input ciphertext.
- </p>
- </li>
- <li>
- <p>
- Return <var>plaintext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate an AES key of length
- equal to the <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CFB-8"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- one of <code>"encrypt"</code>, <code>"decrypt"</code>,
- <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
-
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128CFB8"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192CFB8"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256CFB8"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
- object representing an AES key with value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-CFB-8"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128CFB8"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192CFB8"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256CFB8"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> property of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> property of
- <var>normalizedDerivedKeyAlgorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="aes-kw" class="section">
- <h3>20.14. AES-KW</h3>
- <div id="aes-kw-description" class="section">
- <h4>20.14.1. Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"AES-KW"</code> algorithm identifier is used to perform
- key wrapping using AES, as
- described in [<a href="#rfc3394">RFC3394</a>].
- </p>
- </div>
- <div id="aes-kw-registration" class="section">
- <h4>20.14.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"AES-KW"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>wrapKey</td>
- <td>None</td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>unwrapKey</td>
- <td>None</td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-AesKeyGenParams">AesKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="aes-kw-operations" class="section">
- <h4>20.14.3. Operations</h4>
- <dl>
- <dt>Wrap Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>plaintext</var> is not a multiple of 64 bits in length,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>ciphertext</var> be the result of performing the Key Wrap
- operation described in Section 2.2.1 of [<a href="#rfc3394">RFC3394</a>]
- with <var>plaintext</var> as the plaintext to be wrapped and using the default
- Initial Value defined in Section 2.2.3.1 of the same document.
- </p>
- </li>
- <li>
- <p>
- Return <var>ciphertext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Unwrap Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>plaintext</var> be the result of performing the Key Unwrap
- operation described in Section 2.2.2 of [<a href="#rfc3394">RFC3394</a>] with
- <var>ciphertext</var> as the input ciphertext and using the default Initial
- Value defined in Section 2.2.3.1 of the same document.
- </p>
- </li>
- <li>
- <p>
- If the Key Unwrap operation returns an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return <var>plaintext</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesKeyGenParams">AesKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#aes-keygen-params">AesKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesKeyGenParams-length">length</a> property of
- <var>normalizedAlgorithm</var> is not equal to one of
- 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not
- one of <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated AES key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-KW"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to equal the
- <a href="#dfn-AesKeyGenParams-length">length</a> property of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- one of <code>"wrapKey"</code> or <code>"unwrapKey"</code>,
-
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the length in bits of <var>data</var> is not 128, 192 or 256
-
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>data</var> has length 128 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A128KW"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 192 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A192KW"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>If <var>data</var> has length 256 bits:</dt>
- <dd>If the <code>"alg"</code> field of <var>jwk</var> is present, and is
- not <code>"A256KW"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.</dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"enc"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>. </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a>
- object representing an AES key with value <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-AesKeyAlgorithm">AesKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"AES-KW"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to the length, in bits, of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 128:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A128KW"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 192:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A192KW"</code>.</dd>
- <dt>If the <a href="#dfn-AesKeyAlgorithm-length">length</a> attribute of
- <var>key</var> is 256:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"A256KW"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of
- <a href="#dfn-AesDerivedKeyParams">AesDerivedKeyParams</a> are not present in
- <var>normalizedDerivedKeyAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not 128, 192 or 256,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return the <a href="#dfn-AesDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="hmac" class="section">
- <h3>20.15. HMAC</h3>
- <div id="hmac-description" class="section">
- <h4>20.15.1. Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>HMAC</code> algorithm calculates and verifies hash-based message
- authentication codes according to [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>].
- </p>
- </div>
- <div id="hmac-registration" class="section">
- <h4>20.15.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"HMAC"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>sign</td>
- <td>None</td>
- <td>ArrayBuffer</td>
- </tr>
- <tr>
- <td>verify</td>
- <td>None</td>
- <td>boolean</td>
- </tr>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-HmacKeyGenParams">HmacKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-HmacImportParams">HmacImportParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- <tr>
- <td>get key length</td>
- <td><a href="#dfn-HmacDerivedKeyParams">HmacDerivedKeyParams</a></td>
- <td>Integer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="hmac-importparams" class="section">
- <h4>20.15.3. HmacImportParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-HmacImportParams">HmacImportParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The inner hash function to use.</span>
- AlgorithmIdentifier <dfn id="dfn-HmacImportParams-hash">hash</dfn>;
- <span class="comment">// The length (in bits) of the key.</span>
- [EnforceRange] unsigned long <dfn id="dfn-HmacImportParams-length">length</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="HmacKeyAlgorithm-dictionary" class="section">
- <h4>20.15.4. HmacKeyAlgorithm dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
- <span class="comment">// The inner hash function to use.</span>
- KeyAlgorithm <dfn id="dfn-HmacKeyAlgorithm-hash">hash</dfn>;
- <span class="comment">// The length (in bits) of the key.</span>
- unsigned long <dfn id="dfn-HmacKeyAlgorithm-length">length</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="hmac-keygen-params" class="section">
- <h4>20.15.5. HmacKeyGenParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-HmacKeyGenParams">HmacKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The inner hash function to use.</span>
- AlgorithmIdentifier <dfn id="dfn-HmacKeyGenParams-hash">hash</dfn>;
- <span class="comment">// The length (in bits) of the key to generate. If unspecified, the
- // recommended length will be used, which is the size of the associated hash function's block
- // size.</span>
- [EnforceRange] unsigned long <dfn id="dfn-HmacKeyGenParams-length">length</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="hmac-derivedkey-params" class="section">
- <h4>20.15.6. HmacDerivedKeyParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-HmacDerivedKeyParams">HmacDerivedKeyParams</dfn> : <a href="#dfn-HmacImportParams">HmacImportParams</a> {
- <span class="comment">// The length (in bits) of the key to generate. If unspecified, the
- // recommended length will be used, which is the size of the associated hash function's block
- // size.</span>
- [EnforceRange] unsigned long <dfn id="dfn-HmacDerivedKeyParams-length">length</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="hmac-operations" class="section">
- <h4>20.15.7. Operations</h4>
- <dl>
- <dt>Sign</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>mac</var> be the result of performing the MAC Generation operation
- described in Section 4 of [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using
- the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
- internal slot of <var>key</var>, the hash function identified by the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> and <var>message</var> as the input data <var>text</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>mac</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Verify</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>mac</var> be the result of performing the MAC Generation operation
- described in Section 4 of [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using
- the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]
- internal slot of <var>key</var>, the hash function identified by the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var> and <var>message</var> as the input data <var>text</var>.
- </p>
- </li>
- <li>
- <p>
- Return true if <var>mac</var> is equal to <var>signature</var> and false
- otherwise.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-HmacKeyGenParams">HmacKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-HmacKeyGenParams-hash">hash</a> member is
- not present in <var>normalizedAlgorithm</var>, then
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacKeyGenParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is not present:
- </dt>
- <dd>
- Let <var>length</var> be the block size in bits of the hash function
- identified by the <a href="#dfn-HmacKeyGenParams-hash">hash</a> member
- of <var>normalizedAlgorithm</var>.
- </dd>
- <dt>
- Otherwise, if the <a href="#dfn-HmacKeyGenParams-length">length</a>
- member of <var>normalizedAlgorithm</var> is non-zero:
- </dt>
- <dd>
- Let <var>length</var> be equal to the
- <a href="#dfn-HmacKeyGenParams-length">length</a>
- member of <var>normalizedAlgorithm</var>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any entry which is not <code>"sign"</code> or
- <code>"verify"</code>, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate a key of length <var>length</var> bits.
- </p>
- </li>
- <li>
- <p>
- If the key generation step fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new
- <a href="#dfn-CryptoKey">CryptoKey</a> object representing the
- generated key.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"HMAC"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a new
- <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to equal the <a href="#dfn-Algorithm-name">name</a>
- member of the <a href="#dfn-HmacKeyGenParams-hash">hash</a>
- member of <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute
- of <var>algorithm</var> to <var>hash</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to be <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains an entry which is not
- <code>"sign"</code> or <code>"verify"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the octet string contained in <var>keyData</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var> is present and has a
- <a href="#dfn-Algorithm-name">name</a> member:
- </dt>
- <dd>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to equal the <a href="#dfn-Algorithm-name">name</a>
- member of the <a href="#dfn-HmacImportParams-hash">hash</a>
- member of <var>normalizedAlgorithm</var>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be the <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary represented by <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"kty"</code> field of <var>jwk</var> is not
- <code>"oct"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>jwk</var> does not meet the requirements of
- Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the octet string obtained by decoding the
- <code>"k"</code> field of <var>jwk</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var> is present and has a
- <a href="#dfn-Algorithm-name">name</a> member:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to equal the <a href="#dfn-Algorithm-name">name</a> member of the <a href="#dfn-HmacImportParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is
- <code>"SHA-1"</code>:
- </dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present
- and is not <code>"HS1"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is
- <code>"SHA-256"</code>:
- </dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present
- and is not <code>"HS256"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is
- <code>"SHA-384"</code>:
- </dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present
- and is not <code>"HS384"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is
- <code>"SHA-512"</code>:
- </dt>
- <dd>
- If the <code>"alg"</code> field of <var>jwk</var> is present
- and is not <code>"HS512"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the <code>alg</code> field of <var>jwk</var> is not present,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is
- <code>"HS1"</code>:
- </dt>
- <dd>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to <code>"SHA-1"</code>.
- </dd>
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is
- to <code>"HS256"</code>:
- </dt>
- <dd>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to <code>"SHA-256"</code>.
- </dd>
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is
- <code>"HS384"</code>:
- </dt>
- <dd>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to <code>"SHA-384"</code>.
- </dd>
- <dt>
- If the <code>"alg"</code> field of <var>jwk</var> is
- <code>"HS512"</code>:
- </dt>
- <dd>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> to <code>"SHA-512"</code>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If the <code>"use"</code> field of <var>jwk</var> is present, and is
- not <code>"sign"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"key_ops"</code> field of <var>jwk</var> is present, and
- is invalid according to the requirements of
- <a href="#jwk">JSON Web Key</a> or
- does not contain all of the specified <var>usages</var> values,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>"ext"</code> field of <var>jwk</var> is present and
- has the value false and <var>extractable</var> is true,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>length</var> be equivalent to the length, in octets, of
- <var>data</var>, multiplied by 8.
- </p>
- </li>
- <li>
- <p>
- If <var>length</var> is zero
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacImportParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is present:
- </dt>
- <dd>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacImportParams-length">length</a> member of
- <var>normalizedAlgorithm</var> is greater than <var>length</var>:
- </dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>
- If the <a href="#dfn-HmacImportParams-length">length</a> member of
- <var>normalizedAlgorithm</var>, is less than or equal to
- <var>length</var> minus eight:
- </dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>
- Otherwise:
- </dt>
- <dd>
- Set <var>length</var> equal to the <a href="#dfn-HmacImportParams-length">
- length</a> member of <var>normalizedAlgorithm</var>.
- </dd>
- </dl>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <code><a href="#dfn-CryptoKey">CryptoKey</a></code>
- object representing an HMAC key with the first <var>length</var>
- bits of <var>data</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"HMAC"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-HmacKeyAlgorithm-length">length</a> attribute of
- <var>algorithm</var> to <var>length</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of
- <var>algorithm</var> to <var>hash</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>format</var> is <code>"raw"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>data</var> be the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>If <var>format</var> is <code>"jwk"</code>:</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>jwk</var> be a new <a href="#dfn-JsonWebKey">JsonWebKey</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <code>kty</code> attribute of <var>jwk</var> to the
- string <code>"oct"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>k</code> attribute of <var>jwk</var> to be a string
- containing the raw octets of the key represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>, encoded according to Section 6.4 of <a href="#jwa">JSON Web Algorithms</a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>hash</var> be the
- <a href="#dfn-HmacKeyAlgorithm-hash">hash</a> attribute of
- <var>algorithm</var>.
- </p>
- </li>
-
- <li>
- <dl class="switch">
- <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is <code>"SHA-1"</code>:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"HS1"</code>.</dd>
- <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is <code>"SHA-256"</code>:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"HS256"</code>.</dd>
- <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is <code>"SHA-384"</code>:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"HS384"</code>.</dd>
- <dt>If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>hash</var> is <code>"SHA-512"</code>:</dt>
- <dd>Set the <code>alg</code> attribute of <var>jwk</var> to
- the string <code>"HS512"</code>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Set the <code>key_ops</code> attribute of <var>jwk</var> to equal the
- <a href="#dfn-CryptoKey-usages">usages</a> attribute of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <code>ext</code> attribute of <var>jwk</var> to equal the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of converting <var>jwk</var>
- to an ECMAScript Object, as defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get key length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-HmacImportParams">HmacImportParams</a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-HmacImportParams-hash">hash</a> member is
- not present in <var>normalizedDerivedKeyAlgorithm</var>, then
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-HmacDerivedKeyParams-length">length</a> member of
- <var>normalizedDerivedKeyAlgorithm</var> is not present:
- </dt>
- <dd>
- Let <var>length</var> be the block size in bytes of the hash function
- identified by the <a href="#dfn-HmacImportParams-hash">hash</a> member
- of <var>normalizedDerivedKeyAlgorithm</var>.
- </dd>
- <dt>
- Otherwise, if the <a href="#dfn-HmacDerivedKeyParams-length">length</a>
- member of <var>normalizedDerivedKeyAlgorithm</var> is non-zero:
- </dt>
- <dd>
- Let <var>length</var> be equal to the
- <a href="#dfn-HmacDerivedKeyParams-length">length</a>
- member of <var>normalizedDerivedKeyAlgorithm</var>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>length</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
- <div id="dh" class="section">
- <h3>20.16. Diffie-Hellman</h3>
- <div id="dh-description" class="section">
- <h4>20.16.1. Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- This describes using Diffie-Hellman for key generation and key agreement, as specified
- by <a href="#PKCS3">PKCS #3</a>.
- </p>
- </div>
- <div id="dh-registration" class="section">
- <h4>20.16.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"DH"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>generateKey</td>
- <td><a href="#dfn-DhKeyGenParams">DhKeyGenParams</a></td>
- <td><a href="#dfn-CryptoKeyPair">CryptoKeyPair</a></td>
- </tr>
- <tr>
- <td>deriveBits</td>
- <td><a href="#dfn-DhKeyDeriveParams">DhKeyDeriveParams</a></td>
- <td>Octet string</td>
- </tr>
- <tr>
- <td>importKey</td>
- <td><a href="#dfn-DhImportKeyParams">DhImportKeyParams</a></td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>exportKey</td>
- <td>None</td>
- <td>object</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="dh-DhKeyGenParams" class="section">
- <h4>20.16.3. DhKeyGenParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-DhKeyGenParams">DhKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The prime p.</span>
- BigInteger <dfn id="dfn-DhKeyGenParams-prime">prime</dfn>;
- <span class="comment">// The base g.</span>
- BigInteger <dfn id="dfn-DhKeyGenParams-generator">generator</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="dh-DhKeyAlgorithm" class="section">
- <h4>20.16.4. DhKeyAlgorithm dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-DhKeyAlgorithm">DhKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
- <span class="comment">// The prime p.</span>
- BigInteger <dfn id="dfn-DhKeyAlgorithm-prime">prime</dfn>;
- <span class="comment">// The base g.</span>
- BigInteger <dfn id="dfn-DhKeyAlgorithm-generator">generator</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="dh-DhKeyDeriveParams" class="section">
- <h4>20.16.5. DhKeyDeriveParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-DhKeyDeriveParams">DhKeyDeriveParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The peer's public value.</span>
- <a href="#dfn-CryptoKey">CryptoKey</a> <dfn id="dfn-DhKeyDeriveParams-public">public</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="dh-DhImportKeyParams" class="section">
- <h4>20.16.6. DhImportKeyParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-DhImportKeyParams">DhImportKeyParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The prime p.</span>
- BigInteger <dfn id="dfn-DhImportKeyParams-prime">prime</dfn>;
- <span class="comment">// The base g.</span>
- BigInteger <dfn id="dfn-DhImportKeyParams-generator">generator</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="dh-operations" class="section">
- <h4>20.16.7. Operations</h4>
- <dl>
- <dt>Generate Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-DhKeyGenParams">DhKeyGenParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-DhKeyGenParams">DhKeyGenParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains a value which is not
- one of <code>"deriveKey"</code> or <code>"deriveBits"</code>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate a Diffie-Hellman key pair, as defined in Section 7 of
- [<a href="#PKCS3">PKCS #3</a>], with prime, <var>p</var>, and base,
- <var>g</var>, as specified in the
- <a href="#dfn-DhKeyGenParams-prime">prime</a> and
- <a href="#dfn-DhKeyGenParams-generator">generator</a> properties of
- <var>normalizedAlgorithm</var>, respectively.
- </p>
- </li>
- <li>
- <p>
- If performing the operation results in an error,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-Algorithm-name">name</a> member of
- <var>algorithm</var> to <code>"DH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-DhKeyGenParams-prime">prime</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a>
- attribute of <var>algorithm</var> to equal the
- <a href="#dfn-DhKeyGenParams-generator">generator</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the public key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> to <code>"public"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>publicKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>publicKey</var> to true.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>publicKey</var> to be the empty list.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKey</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the private key of the generated key pair.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>privateKey</var> to <code>"private"</code>
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>privateKey</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>privateKey</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>privateKey</var> to be <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <a href="#dfn-CryptoKeyPair">CryptoKeyPair</a>
- dictionary.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-publicKey">publicKey</a> attribute
- of <var>result</var> to be <var>publicKey</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-CryptoKeyPair-privateKey">privateKey</a> attribute
- of <var>result</var> to be <var>privateKey</var>.
- </p>
- </li>
- <li>
- <p>
- Return the result of converting <var>result</var> to an ECMAScript Object, as
- defined by [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- </ol>
- </dd>
- <dt>Derive Bits</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-DhKeyDeriveParams">DhKeyDeriveParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-DhKeyDeriveParams">DhKeyDeriveParams</a> are not present in
- <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>publicKey</var> be the
- <a href="#dfn-DhKeyDeriveParams-public">public</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> is not <code>"DH"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>publicKey</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> is not equal to the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
- named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of the
- [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>publicKey</var> is not equal to the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal slot of
- <var>key</var>, then <a href="#concept-return-an-error">return an error</a>
- named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Perform the Diffie-Hellman Phase II algorithm as specified in Section 8 of [<a href="#PKCS3">PKCS #3</a>] with <var>key</var> as the DH private value
- <var>x</var> and the Diffie-Hellman public value represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of the <a href="#dfn-DhKeyDeriveParams-public">public</a> member of
- <var>normalizedAlgorithm</var> as the other's public value <var>PV'</var>.
- </p>
- <dl class="switch">
- <dt>If performing the operation results in an error:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- Let <var>secret</var> be the output of the DH Phase II, <var>SK</var>.
- </dd>
- </dl>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the length of <var>secret</var> in bits is less than
- <var>length</var>:
- </dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </dd>
- <dt>Otherwise:</dt>
- <dd>Return the first <var>length</var> bits of <var>secret</var>.</dd>
- </dl>
- </li>
- </ol>
- </dd>
- <dt>Import Key</dt>
- <dd>
- <dl class="switch">
- <dt>
- If <var>format</var> is <code>"raw"</code>:
- </dt>
- <dd>
- <div class="ednote"><div class="ednoteHeader">Editorial note</div>
- <p>
- Raw import of private values is presently not supported.
- </p>
- </div>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-DhImportKeyParams">DhImportKeyParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-DhImportKeyParams">DhImportKeyParams</a> are not present in
- <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>extractable</var> is false,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>PV</var> be the integer which results from interpreting the
- octets of <var>keyData</var> as an unsigned big integer with most
- significant octet first.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing a Diffie-Hellman public key with public value <var>PV</var>
- and with prime, <var>p</var> and base, <var>g</var> equal to the <a href="#dfn-DhImportKeyParams-prime">prime</a> and <a href="#dfn-DhImportKeyParams-generator">generator</a> properties of
- <var>normalizedAlgorithm</var> respectively.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"public"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-Algorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"DH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
- <var>algorithm</var> to equal the <a href="#dfn-DhImportKeyParams-prime">prime</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
- <var>algorithm</var> to equal the <a href="#dfn-DhImportKeyParams-generator">generator</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
- of <var>key</var> to <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>
- If <var>format</var> is <code>"spki"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>spki</var> be the result of running the <a href="#concept-parse-a-spki">parse a subjectPublicKeyInfo</a> algorithm
- over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var> is not
- equivalent to the <code>dhKeyAgreement</code> OID defined in Section 9 of
- [<a href="#PKCS3">PKCS #3</a>], then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the <code>algorithm</code>
- AlgorithmIdentifier field of <var>spki</var> is absent, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>algorithm</code> AlgorithmIdentifier field of <var>spki</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not an instance of the <code>DHParameter</code>
- ASN.1 type defined in Section 9 of <a href="#PKCS3">PKCS #3</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the Diffie-Hellman public key obtained by parsing the
- <code>subjectPublicKey</code> field of <var>spki</var> as an ASN.1
- INTEGER.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"public"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-Algorithm-name">name</a> member of
- <var>algorithm</var> to <code>"DH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
- <var>algorithm</var> to a new <code>BigInteger</code> equal to the
- octet string encoding of the <code>prime</code> field of
- <var>params</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
- <var>algorithm</var> to a new <code>BigInteger</code> equal to the
- octet string encoding of the <code>base</code> field of
- <var>params</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
- of <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>
- If <var>format</var> is <code>"pkcs8"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains a value which is not one of
- <code>"deriveKey"</code> or <code>"deriveBits"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>privateKeyInfo</var> be the result of running the
- <a href="#concept-parse-a-privateKeyInfo">parse a privateKeyInfo</a>
- algorithm over <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- If an error occurred while parsing, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>algorithm</code> object identifier field of the
- <code>algorithm</code> AlgorithmIdentifier field of
- <var>privateKeyInfo</var> is not equivalent to the
- <code>dhKeyAgreement</code> OID defined in Section 9 of [<a href="#PKCS3">PKCS #3</a>], then <a href="#concept-return-an-error">return
- an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field of
- <var>privateKeyInfo</var> is absent, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>params</var> be the <code>parameters</code> field of the
- <code>privateKeyAlgorithm</code> PrivateKeyAlgorithmIdentifier field of
- <var>privateKeyInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If <var>params</var> is not an instance of the <code>DHParameter</code>
- ASN.1 type defined in Section 9 of <a href="#PKCS3">PKCS #3</a>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
+ </div>
+ <div id="hkdf2-ctr-operations" class="section">
+ <h4>37.4. Operations</h4>
+ <dl>
+ <dt>Derive Bits</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>length</var> is null, then <a href="#concept-return-an-error">return
+ an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var> does not describe a <a href="#algorithms">
+ recognized algorithm</a> that supports the digest operation, then
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>extractKey</var> be a key equal to <var>n</var> zero bits where
+ <var>n</var> is the size of the output of the hash function described by the
+ <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>prf</var> be the MAC Generation function described in Section 4 of
+ [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using the hash function
+ described by the <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>keyDerivationKey</var> be the result of performing <var>prf</var>
+ using <var>extractKey</var> as the key and the secret represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ as the message.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of performing the KDF in counter
+ mode operation described in Section 5.1 of NIST SP 800-108
+ [<a href="#SP800-108">SP800-108</a>] using:
+ </p>
+ <ul>
+ <li>
+ <p>
+ <var>prf</var> as the Pseudo-Random Function, <var>PRF</var>,
+ </p>
+ </li>
+ <li>
+ <p>
+ <var>keyDerivationKey</var> as the Key derivation key,
+ <var>K<sub>I</sub></var>,
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-HkdfCtrParams-label">label</a> member of
+ <var>normalizedAlgorithm</var> as <var>Label</var>,
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-HkdfCtrParams-label">context</a> member of
+ <var>normalizedAlgorithm</var> as <var>Context</var>,
+ </p>
+ </li>
+ <li>
+ <p>
+ <var>length</var> as the value of <var>L</var>,
+ </p>
+ </li>
+ <li>
+ <p>
+ 32 as the value of <var>r</var>, and
+ </p>
+ </li>
+ <li>
+ <p>
+ the 32-bit little-endian binary encoding of <var>length</var>
+ as the encoded length value [<var>L</var>]<sub>2</sub>.
+ </p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ If the key derivation operation fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import key</dt>
+ <dd>
+ <dl class="switch">
+ <dt>
+ If <var>format</var> is <code>"raw"</code>:
+ </dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains a value that is not
+ <code>"deriveKey"</code> or <code>"deriveBits"</code>,
+
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the Diffie-Hellman private key obtained by parsing the
- <code>privateKey</code> field of <var>privateKeyInfo</var> as an ASN.1
- INTEGER.
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"private"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-DhKeyAlgorithm">DhKeyAlgorithm</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-Algorithm-name">name</a> member of
- <var>algorithm</var> to <code>"DH"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
- <var>algorithm</var> to a new <code>BigInteger</code> equal to the
- octet string encoding of the <code>prime</code> field of
- <var>params</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-DhKeyAlgorithm-generator">generator</a> attribute of
- <var>algorithm</var> to a new <code>BigInteger</code> equal to the
- octet string encoding of the <code>base</code> field of
- <var>params</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
- of <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </dd>
- <dt>Export Key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If the underlying cryptographic key material represented by the [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- cannot be accessed, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If <var>format</var> is <code>"raw"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <dl class="switch">
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>"public"</code>:
- </dt>
- <dd>
- Let <var>data</var> be the Public Value, <var>PV</var>, associated
- with <var>key</var> as specified in Section 7 of [<a href="#PKCS3">PKCS #3</a>].
- </dd>
- <dt>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is <code>"private"</code>:
- </dt>
- <dd>
- Let <var>data</var> be the octet string that represents the private
- value <var>x</var> associated with <var>key</var> as a big integer,
- most significant octet first.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>
- If <var>format</var> is <code>"spki"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"public"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a href="#concept-encode-a-subjectPublicKeyInfo">encoding a
- subjectPublicKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithmIdentifier</var> field to an
- <code>AlgorithmIdentifier</code> ASN.1 structure with the
- following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the
- <code>dhKeyAgreement</code> OID defined in Section 9 of <a href="#PKCS3">PKCS #3</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>DHParams</code> ASN.1 structure defined in Section 9 of
- <a href="#PKCS3">PKCS #3</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>prime</var> field to an ASN.1 INTEGER that is
- equivalent to the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>base</var> field to an ASN.1 INTEGER that is
- equivalent to the <a href="#dfn-DhKeyAlgorithm-generator">generator</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>subjectPublicKey</var> to an ASN.1 INTEGER that
- corresponds to the Diffie-Hellman public value represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of
- <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>
- If <var>format</var> is <code>"pkcs8"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot
- of <var>key</var> is not <code>"private"</code>, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-InvalidAccessError"><code>InvalidAccessError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>data</var> be the result of <a href="#concept-encode-a-privateKeyInfo">encoding a
- privateKeyInfo</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>privateKeyAlgorithm</var> field to a
- <code>PrivateKeyAlgorithmIdentifier</code> ASN.1 structure with
- the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>algorithm</var> field to the
- <code>dhKeyAgreement</code> OID defined in Section 9 of <a href="#PKCS3">PKCS #3</a>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>parameters</var> field to an instance of the
- <code>DHParams</code> ASN.1 structure defined in Section 9 of
- <a href="#PKCS3">PKCS #3</a> with the following properties:
- </p>
- <ul>
- <li>
- <p>
- Set the <var>prime</var> field to an ASN.1 INTEGER that is
- equivalent to the <a href="#dfn-DhKeyAlgorithm-prime">prime</a> attribute of
- the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- <li>
- <p>
- Set the <var>base</var> field to an ASN.1 INTEGER that is
- equivalent to the <a href="#dfn-DhKeyAlgorithm-generator">generator</a>
- attribute of the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]]
- internal slot of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Set the <var>privateKey</var> field to an ASN.1 INTEGER that
- corresponds to the Diffie-Hellman private value represented by
- [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot
- of <var>key</var>.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Let <var>result</var> be a new <code>ArrayBuffer</code> containing
- <var>data</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
- <div id="sha" class="section">
- <h3>20.17. SHA</h3>
- <div id="sha-description" class="section">
- <h4>20.17.1. Description</h4>
- <p>
- This describes the SHA-1 and SHA-2 families, as specified by
- [<a href="#FIPS180-4">FIPS PUB 180-4</a>].
- </p>
- </div>
- <div id="sha-registration" class="section">
- <h4>20.17.2. Registration</h4>
- <p>
- The following algorithms are added as <a href="#recognized-algorithm-name">
- recognized algorithm names</a>:
- </p>
- <dl>
- <dt id="alg-sha-1"><code>"SHA-1"</code></dt>
- <dd>The SHA-1 algorithm as specified in Section 6.1</dd>
- <dt id="alg-sha-256"><code>"SHA-256"</code></dt>
- <dd>The SHA-256 algorithm as specified in Section 6.2</dd>
- <dt id="alg-sha-384"><code>"SHA-384"</code></dt>
- <dd>The SHA-384 algorithm as specified in Section 6.5</dd>
- <dt id="alg-sha-512"><code>"SHA-512"</code></dt>
- <dd>The SHA-512 algorithm as specified in Section 6.4</dd>
- </dl>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>digest</td>
- <td>None</td>
- <td>ArrayBuffer</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="sha-operations" class="section">
- <h4>20.17.3. Operations</h4>
- <dl>
- <dt>Digest</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Algorithm">Algorithm</a>.
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> is a cases-sensitive string match for
- <code>"SHA-1"</code>:
- </dt>
- <dd>
- Let <var>result</var> be the result of performing the SHA-1 hash function
- defined in Section 6.1 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
- <var>message</var> as the input message, <var>M</var>.
- </dd>
- <dt>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> is a cases-sensitive string match for
- <code>"SHA-256"</code>:
- </dt>
- <dd>
- Let <var>result</var> be the result of performing the SHA-256 hash function
- defined in Section 6.2 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
- <var>message</var> as the input message, <var>M</var>.
- </dd>
- <dt>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> is a cases-sensitive string match for
- <code>"SHA-384"</code>:
- </dt>
- <dd>
- Let <var>result</var> be the result of performing the SHA-384 hash function
- defined in Section 6.5 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
- <var>message</var> as the input message, <var>M</var>.
- </dd>
- <dt>
- If the <a href="#dfn-Algorithm-name">name</a> member of
- <var>normalizedAlgorithm</var> is a cases-sensitive string match for
- <code>"SHA-512"</code>:
- </dt>
- <dd>
- Let <var>result</var> be the result of performing the SHA-1 hash function
- defined in Section 6.4 of [<a href="#FIPS180-4">FIPS PUB 180-4</a>] using
- <var>message</var> as the input message, <var>M</var>.
- </dd>
- </dl>
- </li>
- <li>
- <p>
- If performing the operation results in an error, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return a new ArrayBuffer containing <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
- <div id="concatkdf" class="section">
- <h3>20.18. Concat KDF</h3>
- <div id="concatkdf-description" class="section">
- <h4>20.18.1. Description</h4>
- <p>
- The <code>"CONCAT"</code> algorithm identifier is used to perform key derivation
- using the key derivation algorithm defined in Section 5.8.1 of NIST SP 800-56A
- [<a href="#SP800-56A">SP800-56A</a>].
- </p>
- </div>
- <div id="concatkdf-registration" class="section">
- <h4>20.18.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"CONCAT"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>deriveBits</td>
- <td><a href="#dfn-ConcatParams">ConcatParams</a></td>
- <td>Octet string</td>
- </tr>
- <tr>
- <td>Import key</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>Get key length</td>
- <td>None</td>
- <td>Integer or null</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="concat-params" class="section">
- <h4>20.18.3. ConcatParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-ConcatParams">ConcatParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The digest method to use to derive the keying material.</span>
- AlgorithmIdentifier <dfn id="dfn-ConcatParams-hash">hash</dfn>;
-
- <span class="comment">// A bit string corresponding to the AlgorithmId field of the OtherInfo parameter.</span>
- <span class="comment">// The AlgorithmId indicates how the derived keying material will be parsed and for which</span>
- <span class="comment">// algorithm(s) the derived secret keying material will be used.</span>
- CryptoOperationData <dfn id="dfn-ConcatParams-algorithmId">algorithmId</dfn>;
- <span class="comment">// A bit string that corresponds to the PartyUInfo field of the OtherInfo parameter.</span>
- CryptoOperationData <dfn id="dfn-ConcatParams-partyUInfo">partyUInfo</dfn>;
- <span class="comment">// A bit string that corresponds to the PartyVInfo field of the OtherInfo parameter.</span>
- CryptoOperationData <dfn id="dfn-ConcatParams-partyVInfo">partyVInfo</dfn>;
- <span class="comment">// An optional bit string that corresponds to the SuppPubInfo field of the OtherInfo parameter.</span>
- CryptoOperationData? <dfn id="dfn-ConcatParams-publicInfo">publicInfo</dfn>;
- <span class="comment">// An optional bit string that corresponds to the SuppPrivInfo field of the OtherInfo parameter.</span>
- CryptoOperationData? <dfn id="dfn-ConcatParams-privateInfo">privateInfo</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="concat-operations" class="section">
- <h4>20.18.4. Operations</h4>
- <dl>
- <dt>Derive Bits</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-ConcatParams">ConcatParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the
- <a href="#dfn-ConcatParams-hash">hash</a>,
- <a href="#dfn-ConcatParams-algorithmId">algorithmId</a>,
- <a href="#dfn-ConcatParams-partyUInfo">partyUInfo</a> or
- <a href="#dfn-ConcatParams-partyVInfo">partyVInfo</a> properties are not
- present in <var>normalizedAlgorithm</var>, then
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>secret</var> be the result of performing the Concatenation Key
- Derivation Function defined in Section 5.8.1 of
- [<a href="#SP800-56A">SP800-56A</a>] with <var>length</var> as
- <var>keydatalen</var>, the hash function identified by the
- <a href="#dfn-ConcatParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var> as <var>H</var>, the
- <a href="#dfn-ConcatParams-algorithmId">algorithmId</a> member of
- <var>normalizedAlgorithm</var> as <var>AlgorithmID</var>, the
- <a href="#dfn-ConcatParams-partyUInfo">partyUInfo</a> member of
- <var>normalizedAlgorithm</var> as <var>PartyUInfo</var>, the
- <a href="#dfn-ConcatParams-partyVInfo">partyVInfo</a> member of
- <var>normalizedAlgorithm</var> as <var>PartyVInfo</var>, the
- <a href="#dfn-ConcatParams-publicInfo">publicInfo</a> member of
- <var>normalizedAlgorithm</var>, if present and not null, as
- <var>publicInfo</var> and the
- <a href="#dfn-ConcatParams-privateInfo">privateInfo</a> member of
- <var>normalizedAlgorithm</var>, if present and not null, as
- <var>privateInfo</var>.
- </p>
- </li>
- <li>
- <p>
- If the operation fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return <var>secret</var>
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import key</dt>
- <dd>
- <dl class="switch">
- <dt>
- If <var>format</var> is <code>"raw"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains a value that is not
- <code>"deriveKey"</code> or <code>"deriveBits"</code>,
-
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the key data provided in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"secret"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"CONCAT"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
- of <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </dd>
- <dt>Get length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Return null.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
- <div id="hkdf-ctr" class="section">
- <h3>20.19. HKDF-CTR</h3>
- <div id="hkdf-ctr-description" class="section">
- <h4>20.19.1. Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"HKDF-CTR"</code> algorithm identifier is used to
- perform key derivation using the extraction-then-expansion approach described in
- NIST SP 800-56C[<a href="#SP800-56C">SP800-56C</a>], using HMAC in counter mode,
- as described in Section 5.1 of NIST SP 800-108
- [<a href="#SP800-108">SP800-108</a>].
- </p>
- </div>
- <div id="hkdf-ctr-registration" class="section">
- <h4>20.19.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a>
- for this algorithm is <code>"HKDF-CTR"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>deriveBits</td>
- <td><a href="#dfn-HkdfCtrParams">HkdfCtrParams</a></td>
- <td><a href="#dfn-ArrayBuffer">ArrayBuffer</a></td>
- </tr>
- <tr>
- <td>Import key</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>Get key length</td>
- <td>None</td>
- <td>Integer or null</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="hkdf-ctr-params" class="section">
- <h4>20.19.3. HkdfCtrParams dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-HkdfCtrParams">HkdfCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- <span class="comment">// The algorithm to use with HMAC (e.g.: <a href="#sha-256">SHA-256</a>)</span>
- AlgorithmIdentifier <dfn id="dfn-HkdfCtrParams-hash">hash</dfn>;
- <span class="comment">// A bit string that corresponds to the label that identifies the purpose for the derived keying material.</span>
- CryptoOperationData <dfn id="dfn-HkdfCtrParams-label">label</dfn>;
- <span class="comment">// A bit string that corresponds to the context of the key derivation, as described in Section 5 of NIST SP 800-108 [<a href="#SP800-108">SP800-108</a>]</span>
- CryptoOperationData <dfn id="dfn-HkdfCtrParams-context">context</dfn>;
-};
- </code></pre></div></div>
- <div class="ednote"><div class="ednoteHeader">Editorial note</div>
- <p>
- The definition of HKDF allows the caller to supply an optional pseudorandom salt
- value, which is used as the key during the extract phase. If this value is not
- supplied, an all zero string is used instead. However, support for an explicit
- salt value is not widely implemented in existing APIs, nor is it required by
- existing usages of HKDF. Should this be an optional parameter, and if so, what
- should the behavior be of a user agent that does not support explicit salt
- values (is it conforming or non-conforming?)
- </p>
- </div>
- </div>
- <div id="hkdf2-ctr-operations" class="section">
- <h4>20.19.4. Operations</h4>
- <dl>
- <dt>Derive Bits</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>length</var> is null,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-HkdfCtrParams">HkdfCtrParams</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-HkdfCtrParams">HkdfCtrParams</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var> does not describe a <a href="#algorithms">
- recognized algorithm</a> that supports the digest operation, then
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
- </p>
- </li>
- <li>
- <p>
- Let <var>extractKey</var> be a key equal to <var>n</var> zero bits where
- <var>n</var> is the size of the output of the hash function described by the
- <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>prf</var> be the MAC Generation function described in Section 4 of
- [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using the hash function
- described by the <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>keyDerivationKey</var> be the result of performing <var>prf</var>
- using <var>extractKey</var> as the key and the secret represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- as the message.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of performing the KDF in counter
- mode operation described in Section 5.1 of NIST SP 800-108
- [<a href="#SP800-108">SP800-108</a>] using:
- </p>
- <ul>
- <li>
- <p>
- <var>prf</var> as the Pseudo-Random Function, <var>PRF</var>,
- </p>
- </li>
- <li>
- <p>
- <var>keyDerivationKey</var> as the Key derivation key,
- <var>K<sub>I</sub></var>,
- </p>
- </li>
- <li>
- <p>
- <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-HkdfCtrParams-label">label</a> member of
- <var>normalizedAlgorithm</var> as <var>Label</var>,
- </p>
- </li>
- <li>
- <p>
- <a href="#concept-contents-of-arraybuffer">the contents of</a> the <a href="#dfn-HkdfCtrParams-label">context</a> member of
- <var>normalizedAlgorithm</var> as <var>Context</var>,
- </p>
- </li>
- <li>
- <p>
- <var>length</var> as the value of <var>L</var>,
- </p>
- </li>
- <li>
- <p>
- 32 as the value of <var>r</var>, and
- </p>
- </li>
- <li>
- <p>
- the 32-bit little-endian binary encoding of <var>length</var>
- as the encoded length value [<var>L</var>]<sub>2</sub>.
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- If the key derivation operation fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import key</dt>
- <dd>
- <dl class="switch">
- <dt>
- If <var>format</var> is <code>"raw"</code>:
- </dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains a value that is not
- <code>"deriveKey"</code> or <code>"deriveBits"</code>,
-
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the key data provided in <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"secret"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new
- <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"HKDF-CTR"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
- internal slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
- of <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>
- <a href="#concept-return-an-error">Return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
- </dd>
- </dl>
- </dd>
- <dt>Get length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Return null.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
- </div>
-
- <div id="pbkdf2" class="section">
- <h3>20.20. PBKDF2</h3>
- <div id="pbkdf2-description" class="section">
- <h4>20.20.1. Description</h4>
- <p class="norm">This section is non-normative.</p>
- <p>
- The <code>"PBKDF2"</code> algorithm identifier is used to
- perform key derivation using the PKCS#5 password-based key
- derivation function version 2.0, as defined in
- [<a href="#rfc2898">RFC2898</a>] using HMAC as the pseudo-random function.
- </p>
- </div>
- <div id="pbkdf2-registration" class="section">
- <h4>20.20.2. Registration</h4>
- <p>
- The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
- this algorithm is <code>"PBKDF2"</code>.
- </p>
- <table>
- <thead>
- <tr>
- <th><a href="#supported-operations">Operation</a></th>
- <th><a href="#algorithm-specific-params">Parameters</a></th>
- <th><a href="#algorithm-result">Result</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>generateKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>deriveBits</td>
- <td><a href="#dfn-Pbkdf2Params">Pbkdf2Params</a></td>
- <td><a href="#dfn-ArrayBuffer">ArrayBuffer</a></td>
- </tr>
- <tr>
- <td>importKey</td>
- <td>None</td>
- <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
- </tr>
- <tr>
- <td>Get key length</td>
- <td>None</td>
- <td>Length or null</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div id="pbkdf2-params" class="section">
- <h4>20.20.3. Pbkdf2Params dictionary</h4>
- <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
-dictionary <dfn id="dfn-Pbkdf2Params">Pbkdf2Params</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
- CryptoOperationData <dfn id="dfn-Pbkdf2Params-salt">salt</dfn>;
- [EnforceRange] unsigned long <dfn id="dfn-Pbkdf2Params-iterations">iterations</dfn>;
- AlgorithmIdentifier <dfn id="dfn-Pbkdf2Params-hash">hash</dfn>;
-};
- </code></pre></div></div>
- </div>
- <div id="pbkdf2-operations" class="section">
- <h4>20.20.4. Operations</h4>
- <dl>
- <dt>Derive bits</dt>
- <dd>
- <ol>
- <li>
- <p>
- Let <var>normalizedAlgorithm</var> be the result of
- <a href="#dfn-normalize-to-type">normalizing</a> <var>algorithm</var>
- to <a href="#dfn-Pbkdf2Params">Pbkdf2Params</a>.
- </p>
- </li>
- <li>
- <p>
- If any of the members of <a href="#dfn-Pbkdf2Params">Pbkdf2Params</a> are
- not present in <var>normalizedAlgorithm</var>,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>length</var> is null or is not a multiple of 8, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If the <a href="#dfn-Pbkdf2Params-hash">hash</a> member of
- <var>normalizedAlgorithm</var> does not describe a <a href="#algorithms">
- recognized algorithm</a> that supports the digest operation, then
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
- </p>
- </li>
- <li>
- <p>
- Let <var>prf</var> be the MAC Generation function described in Section 4 of
- [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using the hash function
- described by the <a href="#dfn-Pbkdf2Params-hash">hash</a> member of
- <var>normalizedAlgorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of performing the PBKDF2 operation defined
- in Section 5.2 of [<a href="#rfc2898">RFC2898</a>] using <var>prf</var> as the
- pseudo-random function, <var>PRF</var>, the password represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
- as the password, <var>P</var>, <a href="#concept-contents-of-arraybuffer">the
- contents of</a> the <a href="#dfn-Pbkdf2Params-salt">salt</a> attribute of
- <var>normalizedAlgorithm</var> as the salt, <var>S</var>, the value of the <a href="#dfn-Pbkdf2Params-iterations">iterations</a> attribute of
- <var>normalizedAlgorithm</var> as the iteration count, <var>c</var>, and
- <var>length</var> divided by 8 as the intended key length, <var>dkLen</var>.
- </p>
- </li>
- <li>
- <p>
- If the key derivation operation fails,
- then <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-OperationError"><code>OperationError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Return <var>result</var>
- </p>
- </li>
- </ol>
- </dd>
- <dt>Generate key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>usages</var> contains any element that is not
- <code>"deriveKey"</code>, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- If <var>extractable</var> is true, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Generate a new password by prompting the user.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing the provided password as a series of bytes encoded using UTF-8.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"secret"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"PBKDF2"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Import key</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>format</var> is not <code>"raw"</code>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
- </p>
- </li>
- <li>
- <p>
- If <var>usages</var> contains any element that is not
- <code>"deriveKey"</code>, then <a href="#concept-return-an-error">return an
- error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
- representing <var>keyData</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
- <var>key</var> to <code>"secret"</code>.
- </p>
- </li>
- <li>
- <p>
- Let <var>algorithm</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
- object.
- </p>
- </li>
- <li>
- <p>
- Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
- <var>algorithm</var> to <code>"PBKDF2"</code>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
- slot of <var>key</var> to <var>algorithm</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
- slot of <var>key</var> to <var>extractable</var>.
- </p>
- </li>
- <li>
- <p>
- Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
- <var>key</var> to the <a href="#concept-normalized-usages">normalized
- value</a> of <var>usages</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>key</var>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Get length</dt>
- <dd>
- <ol>
- <li>
- <p>
- Return null.
- </p>
- </li>
- </ol>
- </dd>
- </dl>
- </div>
+ representing the key data provided in <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"secret"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new
+ <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"HKDF-CTR"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]]
+ internal slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot
+ of <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Otherwise:</dt>
+ <dd>
+ <a href="#concept-return-an-error">Return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>.
+ </dd>
+ </dl>
+ </dd>
+ <dt>Get length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Return null.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
</div>
</div>
-
- <div id="algorithm-normalizing-rules" class="section">
- <h2>21. Algorithm normalizing rules</h2>
- <p>
- The <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> typedef permits algorithms
- to be specified as either an <a href="#dfn-Algorithm">Algorithm</a> dictionary or a <a href="#dfn-DOMString">DOMString</a>. The <a href="#dfn-DOMString">DOMString</a> option
- permits algorithms to be specified using shorthand 'aliases'. Algorithms may define
- aliases and the values they correspond to. Using an alias is exactly equivalent to using
- the value corresponding to the alias.
- </p>
- <p>
- Additionally, many algorithms define a subclass of the
- <a href="#dfn-Algorithm">Algorithm</a> type. As a result Web IDL type mapping to the
- correct subclass must be performed at the appropriate time.
- </p>
- <p>
- When this specification says that a value <var>algorithm</var> be <dfn id="concept-normalize-to-type">normalized to <var>type</var></dfn> the user agent must
- perform the following steps:
- </p>
- <ol>
- <li>
- <p>
- Let <var>mappedAlgorithm</var> be the result of mapping <var>algorithm</var> to
- the <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> type as specified in
- [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- <li>
- <dl class="switch">
- <dt>If <var>mappedAlgorithm</var> is a DOMString, then:</dt>
- <dd>
- <ol>
- <li>
- <p>
- If <var>mappedAlgorithm</var> contains any non-ASCII characters,
- <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- <li>
- <p>
- Convert every character in <var>mappedAlgorithm</var> to lower case.
- </p>
- </li>
- <li>
- <p>
- If <var>mappedAlgorithm</var> is equal to a recognized
- <a href="#dfn-algorithm-alias">algorithm alias</a> then let
- <var>objectAlgorithm</var> be the value defined to be equivalent
- to this alias.
- </p>
- </li>
- <li>
- <p>
- Otherwise, <a href="#concept-return-an-error">return an error</a> named
- <a href="#dfn-SyntaxError"><code>SyntaxError</code></a>.
- </p>
- </li>
- </ol>
- </dd>
- <dt>Otherwise:</dt>
- <dd>Let <var>objectAlgorithm</var> equal <var>algorithm</var>.</dd>
- </dl>
- </li>
- <li>
- <p>
- Let <var>result</var> be the result of mapping <var>objectAlgorithm</var> to
- <var>type</var> as specified in [<a href="#WebIDL">WEBIDL</a>].
- </p>
- </li>
- <li>
- <p>
- If a member, <var>memberName</var>, of <var>type</var> has a type that is a union of
- <a href="#dfn-DOMString">DOMString</a> and a type, <var>memberType</var>, that is
- either <a href="#dfn-Algorithm">Algorithm</a> or a subclass of <a href="#dfn-Algorithm">Algorithm</a> and if the <var>memberName</var> member of
- <var>result</var> is present and has type <a href="#dfn-DOMString">DOMString</a>, then
- replace <var>memberName</var> in <var>result</var> with the result of <a href="#dfn-normalize-to-type">normalizing</a> the <var>memberName</var> member of
- <var>result</var> to <var>memberType</var>.
- </p>
- </li>
- <li>
- <p>
- Return <var>result</var>.
- </p>
- </li>
- </ol>
+
+ <div id="pbkdf2" class="section">
+ <h3>38. PBKDF2</h3>
+ <div id="pbkdf2-description" class="section">
+ <h4>38.1. Description</h4>
+ <p class="norm">This section is non-normative.</p>
+ <p>
+ The <code>"PBKDF2"</code> algorithm identifier is used to
+ perform key derivation using the PKCS#5 password-based key
+ derivation function version 2.0, as defined in
+ [<a href="#rfc2898">RFC2898</a>] using HMAC as the pseudo-random function.
+ </p>
+ </div>
+ <div id="pbkdf2-registration" class="section">
+ <h4>38.2. Registration</h4>
+ <p>
+ The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
+ this algorithm is <code>"PBKDF2"</code>.
+ </p>
+ <table>
+ <thead>
+ <tr>
+ <th><a href="#supported-operations">Operation</a></th>
+ <th><a href="#algorithm-specific-params">Parameters</a></th>
+ <th><a href="#algorithm-result">Result</a></th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>generateKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>deriveBits</td>
+ <td><a href="#dfn-Pbkdf2Params">Pbkdf2Params</a></td>
+ <td><a href="#dfn-ArrayBuffer">ArrayBuffer</a></td>
+ </tr>
+ <tr>
+ <td>importKey</td>
+ <td>None</td>
+ <td><a href="#dfn-CryptoKey">CryptoKey</a></td>
+ </tr>
+ <tr>
+ <td>Get key length</td>
+ <td>None</td>
+ <td>Length or null</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div id="pbkdf2-params" class="section">
+ <h4>38.3. Pbkdf2Params dictionary</h4>
+ <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
+dictionary <dfn id="dfn-Pbkdf2Params">Pbkdf2Params</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
+CryptoOperationData <dfn id="dfn-Pbkdf2Params-salt">salt</dfn>;
+[EnforceRange] unsigned long <dfn id="dfn-Pbkdf2Params-iterations">iterations</dfn>;
+<a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-Pbkdf2Params-hash">hash</dfn>;
+};
+ </code></pre></div></div>
+ </div>
+ <div id="pbkdf2-operations" class="section">
+ <h4>38.4. Operations</h4>
+ <dl>
+ <dt>Derive bits</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>length</var> is null or is not a multiple of 8, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the <a href="#dfn-Pbkdf2Params-hash">hash</a> member of
+ <var>normalizedAlgorithm</var> does not describe a <a href="#algorithms">
+ recognized algorithm</a> that supports the digest operation, then
+ <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>prf</var> be the MAC Generation function described in Section 4 of
+ [<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using the hash function
+ described by the <a href="#dfn-Pbkdf2Params-hash">hash</a> member of
+ <var>normalizedAlgorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>result</var> be the result of performing the PBKDF2 operation defined
+ in Section 5.2 of [<a href="#rfc2898">RFC2898</a>] using <var>prf</var> as the
+ pseudo-random function, <var>PRF</var>, the password represented by [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
+ as the password, <var>P</var>, <a href="#concept-contents-of-arraybuffer">the
+ contents of</a> the <a href="#dfn-Pbkdf2Params-salt">salt</a> attribute of
+ <var>normalizedAlgorithm</var> as the salt, <var>S</var>, the value of the <a href="#dfn-Pbkdf2Params-iterations">iterations</a> attribute of
+ <var>normalizedAlgorithm</var> as the iteration count, <var>c</var>, and
+ <var>length</var> divided by 8 as the intended key length, <var>dkLen</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the key derivation operation fails,
+ then <a href="#concept-return-an-error">return an error</a> named
+ <a href="#dfn-OperationError"><code>OperationError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>result</var>
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Generate key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>usages</var> contains any element that is not
+ <code>"deriveKey"</code>, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>extractable</var> is true, then <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate a new password by prompting the user.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing the provided password as a series of bytes encoded using UTF-8.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"secret"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"PBKDF2"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Import key</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ If <var>format</var> is not <code>"raw"</code>, <a href="#concept-return-an-error">return an error</a> named <a href="#dfn-NotSupportedError"><code>NotSupportedError</code></a>
+ </p>
+ </li>
+ <li>
+ <p>
+ If <var>usages</var> contains any element that is not
+ <code>"deriveKey"</code>, then <a href="#concept-return-an-error">return an
+ error</a> named <a href="#dfn-DataError"><code>DataError</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>key</var> be a new <a href="#dfn-CryptoKey">CryptoKey</a> object
+ representing <var>keyData</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-type">type</a>]] internal slot of
+ <var>key</var> to <code>"secret"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Let <var>algorithm</var> be a new <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a>
+ object.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
+ <var>algorithm</var> to <code>"PBKDF2"</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-algorithm">algorithm</a>]] internal
+ slot of <var>key</var> to <var>algorithm</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-extractable">extractable</a>]] internal
+ slot of <var>key</var> to <var>extractable</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Set the [[<a href="#dfn-CryptoKey-slot-usages">usages</a>]] internal slot of
+ <var>key</var> to the <a href="#concept-normalized-usages">normalized
+ value</a> of <var>usages</var>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Return <var>key</var>.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ <dt>Get length</dt>
+ <dd>
+ <ol>
+ <li>
+ <p>
+ Return null.
+ </p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </div>
</div>
+
+
<div id="examples-section" class="section">
- <h2>22. JavaScript Example Code</h2>
+ <h2>39. JavaScript Example Code</h2>
<div id="examples-signing" class="section">
- <h3>22.1. Generate a signing key pair, sign some data</h3>
+ <h3>39.1. Generate a signing key pair, sign some data</h3>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
<span class="comment">// Algorithm Object</span>
@@ -15835,7 +15348,7 @@
</code></pre></div></div>
</div>
<div id="examples-symmetric-encryption" class="section">
- <h3>22.2. Symmetric Encryption</h3>
+ <h3>39.2. Symmetric Encryption</h3>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
var clearDataArrayBufferView = convertPlainTextToArrayBufferView("Plain Text Data");
<span class="comment">// TODO: create example utility function that converts text -> ArrayBufferView</span>
@@ -15863,9 +15376,9 @@
</div>
</div>
<div id="iana-section" class="section">
- <h2>23. IANA Considerations</h2>
+ <h2>40. IANA Considerations</h2>
<div id="iana-section-jws-jwa" class="section">
- <h3>23.1. JSON Web Signature and Encryption Algorithms Registration</h3>
+ <h3>40.1. JSON Web Signature and Encryption Algorithms Registration</h3>
<p>
This section registers the following algorithm identifiers in the IANA JSON Web
Signature and Encryption Algorithms Registry for use with JSON Web Key. Note that the
@@ -16003,7 +15516,7 @@
</ul>
</div>
<div id="iana-section-jwk" class="section">
- <h3>23.2. JSON Web Key Parameters Registration</h3>
+ <h3>40.2. JSON Web Key Parameters Registration</h3>
<ul>
<li>Parameter Name: "ext"</li>
<li>Parameter Description: Extractable</li>
@@ -16015,7 +15528,7 @@
</div>
</div>
<div id="acknowledgements-section" class="section">
- <h2>24. Acknowledgements</h2>
+ <h2>41. Acknowledgements</h2>
<p>
The editors would like to thank Adam Barth, Alex Russell, Ali Asad, Arun Ranganathan,
Brian Smith, Brian Warner, Channy Yun, Eric Roman, Glenn Adams, Jim Schaad, Kai Engert,
@@ -16038,9 +15551,9 @@
</p>
</div>
<div id="references" class="section">
- <h2>25. References</h2>
+ <h2>42. References</h2>
<div id="normative-references" class="section">
- <h3>25.1. Normative References</h3>
+ <h3>42.1. Normative References</h3>
<dl>
<dt id="DOM4">DOM4</dt>
<dd>
@@ -16133,7 +15646,7 @@
</dl>
</div>
<div id="informative-references" class="section">
- <h3>25.2. Informative References</h3>
+ <h3>42.2. Informative References</h3>
<dl>
<dt id="CDSA">CDSA</dt>
<dd>