Abstract

This specification describes a JavaScript API for performing basic
cryptographic operations in web applications, such as hashing,
signature generation and verification, and encryption and decryption.
Additionally, it describes an API for applications to generate and/or
manage the keying material necessary to perform these operations.
Uses for this API range from user or service authentication, document
or code signing, and the confidentiality and integrity of
communications.

Editorial note

There are 19 further editorial notes in the document.

Status of this Document

Publication as a Last Call Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This section describes the status of this document at the time of
its publication. Other documents may supersede this document. A list
of current W3C publications and the latest revision of this technical
report can be found in the W3C technical
reports index at http://www.w3.org/TR/.

Implementors should be aware that this specification is not stable.
Implementors who are not taking part in the discussions are likely to find the
specification changing out from under them in incompatible ways. Vendors interested
in implementing this specification before it eventually reaches the Candidate Recommendation
stage should join the mailing lists that follow and take part in the discussions.

This document was published by the Web Cryptography Working Group as a Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webcrypto-comments@w3.org, the W3C's public email list for issues related to Web Cryptography. Archives of the public list and archives of the member's-only list are available. The Last Call period ends 20 May 2014. All comments are welcome.

In particular, the Web Cryptography Working Group invites discussion and feedback on this draft document by web developers, companies, standardization bodies or forums interested in deployment of secure services with web applications. Specifically, Web Cryptography Working Group is looking for priority feedback on:

1. Introduction

This section is non-normative.

The Web Cryptography API defines a low-level interface to interacting with cryptographic
key material that is managed or exposed by user agents. The API itself is agnostic of
the underlying implementation of key storage, but provides a common set of interfaces
that allow rich web applications to perform operations such as signature generation and
verification, hashing and verification, encryption and decryption, without requiring
access to the raw keying material.

Cryptographic transformations are exposed via the
SubtleCrypto interface, which defines a common set
of methods and events for dealing with initialization, processing data, and completing
the operation to yield the final output. In addition to operations such as signature
generation and verification, hashing and verification, and encryption and decryption,
the API provides interfaces for key generation, key derivation, key import and export,
and key discovery.

2. Use Cases

This section is non-normative

2.1. Multi-factor Authentication

A web application may wish to extend or replace existing username/password based
authentication schemes with authentication methods based on proving that the user has
access to some secret keying material. Rather than using transport-layer authentication,
such as TLS client certificates, the web application may wish to provide a rich user
experience by providing authentication within the application itself.

Using the Web Cryptography API, such an application could locate suitable client keys,
which may have been previously generated via the user agent or pre-provisioned
out-of-band by the web application. It could then perform cryptographic operations such
as decrypting an authentication challenge followed by signing an authentication response.

Further, the authentication data could be further enhanced by binding the authentication
to the TLS session that the client is authenticating over, by deriving a key based on
properties of the underlying transport.

If a user did not already have a key associated with their account, the web application
could direct the user agent to either generate a new key or to re-use an existing key of
the user's choosing.

2.2. Protected Document Exchange

When exchanging documents that may contain sensitive or personal information, a
web application may wish to ensure that only certain users can view the documents, even
after they have been securely received, such as over TLS. One way that a web application
can do so is by encrypting the documents with a secret key, and then wrapping that key
with the public keys associated with authorized users.

When a user agent navigates to such a web application, the application may send the
encrypted form of the document. The user agent is then instructed to unwrap the encryption
key, using the user's private key, and from there, decrypt and display the document.

2.3. Cloud Storage

When storing data with remote service providers, users may wish to protect the
confidentiality of their documents and data prior to uploading them. The Web
Cryptography API allows an application to have a user select a private or secret key,
to either derive encryption keys from the selected key or to directly encrypt documents
using this key, and then to upload the transformed/encrypted data to the service provider
using existing APIs.

This use case is similar to the Protected Document
Exchange use case because Cloud Storage can be considered as a user exchanging
protected data with himself in the future.

2.4. Document Signing

A web application may wish to accept electronic signatures on documents, in lieu of
requiring physical signatures. An authorized signature may use a key that was
pre-provisioned out-of-band by the web application, or it may be using a key that the
client generated specifically for the web application.

The web application must be able to locate any appropriate keys for signatures, then
direct the user to perform a signing operation over some data, as proof that they accept
the document.

2.5. Data Integrity Protection

When caching data locally, an application may wish to ensure that this data cannot be
modified in an offline attack. In such a case, the server may sign the data that it
intends the client to cache, with a private key held by the server. The web application
that subsequently uses this cached data may contain a public key that enables it to
validate that the cache contents have not been modified by anyone else.

2.6. Secure Messaging

In addition to a number of web applications already offering chat based services, the
rise of WebSockets and RTCWEB allows a great degree of flexibility in inter-user-agent
messaging. While TLS/DTLS may be used to protect messages to web applications, users
may wish to directly secure messages using schemes such as off-the-record (OTR) messaging.

The Web Cryptography API enables OTR, by allowing key agreement to be performed so that
the two parties can negotiate shared encryption keys and message authentication code (MAC)
keys, to allow encryption and decryption of messages, and to prevent tampering of
messages through the MACs.

2.7. Javascript Object Signing and Encryption (JOSE)

A web application wishes to make use of the structures and format of
messages defined by the IETF Javascript Object Signing and Encryption
(JOSE) Working Group. The web application wishes to manipulate public
keys encoded in the JSON key format (JWK), messages that have been
integrity protected using digital signatures or MACs (JWS), or that
have been encrypted (JWE).

3. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams,
examples, and notes in this specification are non-normative. Everything else in
this specification is normative.

A user agent is considered to be a
conforming user agent
if it satisfies all of the MUST-,
REQUIRED- and SHALL-level
criteria in this specification that apply to implementations. This specification
uses both the terms "conforming user agent" and "user agent" to refer to this
product class.

User agents MAY implement algorithms in this
specification in any way desired, so long as the end result is indistinguishable
from the result that would be obtained from the specification's algorithms.

User agents that use ECMAScript to implement the APIs defined in this specification
MUST implement them in a manner consistent with the
ECMAScript Bindings defined in the Web IDL specification [WEBIDL]
as this specification uses that specification and terminology.

Unless otherwise stated, string comparisons are done in a
case-sensitive manner. String literals in this specification
written in monospace font like "this" do not include the enclosing quotes.

4. Scope

This section is non-normative.

4.1. Level of abstraction

The specification attempts to focus on the common functionality and features between
various platform-specific or standardized cryptographic APIs, and avoid features and
functionality that are specific to one or two implementations. As such this API allows
key generation, management, and exchange with a level of abstraction that avoids
developers needing to care about the implementation of the underlying key storage. The
API is focused specifically around Key objects, as an abstraction for the underlying raw
cryptographic keying material. The intent behind this is to allow an API that is generic
enough to allow conforming user agents to expose keys that are stored and managed
directly by the user agent, that may be stored or managed using isolated storage APIs
such as per-user key stores provided by some operating systems, or within key storage
devices such as secure elements, while allowing rich web applications to manipulate the
keys and without requiring the web application be aware of the nature of the underlying
key storage.

4.2. Cryptographic algorithms

Because the underlying cryptographic implementations will vary between conforming user
agents, and may be subject to local policy, including but not limited to concerns such
as government or industry regulation, security best practices, intellectual property
concerns, and constrained operational environments, this specification does not dictate
a mandatory set of algorithms that MUST be implemented.
Instead, it defines a common set of bindings that can be used in an
algorithm-independent manner, a common framework for discovering if a user agent or key
handle supports the underlying algorithm, and a set of conformance requirements for the
behaviours of individual algorithms, if implemented.

4.3. Operations

Although the API does not expose the notion of cryptographic providers or modules, each
key is internally bound to a cryptographic provider or module, so web applications can
rest assured that the right cryptographic provider or module will be used to perform
cryptographic operations involving that key.

4.4. Out of scope

This API, while allowing applications to generate, retrieve, and manipulate keying
material, does not specifically address the provisioning of keys in particular types of
key storage, such as secure elements or smart cards. This is due to such provisioning
operations often being burdened with vendor-specific details that make defining a
vendor-agnostic interface an unsuitably unbounded task. Additionally, this API does not
deal with or address the discovery of cryptographic modules, as such concepts are
dependent upon the underlying user agent and are not concepts that are portable between
common operating systems, cryptographic libraries, and implementations.

5. Security considerations

This section is non-normative.

5.1. Security considerations for implementers

User agents should take care before exposing keys that were not explicitly generated
via the API in this specification or exposing keys that were generated in the
context of other origins. Two applications with access to the same key handle may be
able to spoof messages to each other, as both valid and hostile messages will appear
to be valid for the given key. Because of this, user agents are recommended to obtain
express permission from the user before re-using keys, unless there is a prearranged
trust relationship.

User agents should be aware of the security considerations of each algorithm
implemented and exposed to applications. For a number of algorithms, their
cryptographic strength is relative to the amount of work necessary to compute the
result, whether this be through the generation of significantly large prime numbers or
through the repeatedly iterating through the same algorithm to reduce its
susceptibility to brute force. Implementations should therefore take measures to
ensure against misuse. Such measures may include requiring express user permission to
compute some expensive operations, rate limiting the number of times the application
may call certain APIs/algorithms, and defining implementation-specific upper limits
for inputs such as key sizes or iteration counts, as appropriate for the device on
which the implementation executes.

In some cases, the same underlying cryptographic key material may be re-usable for
multiple algorithms. One such example is an RSA key, which may be used for both
signing and encryption, or with RSA-PKCS1v1.5 and RSA-PSS. In some cases, the re-use
of this key material may undermine the security properties of the key and allow
applications to recover the raw material.

Editorial note

ISSUE-33
One proposed technical solution for user agents is to implement "key tainting", in
which it records how a particular key has been used (eg: algorithms, parameters),
and prevents it from being re-used in a manner that is unsafe or contrary to the
security - such as preventing a PKCS1-v1.5 key from being used with RSA-PSS, or
preventing an RSA-OAEP w/ MGF1-SHA1 from being used with RSA-OAEP w/ MGF1-SHA256.
Questions exist about whether this should be encouraged or permitted, and the
interoperability concerns it might cause.

5.2. Security considerations for authors

While this API provides important functionality for the development of secure
applications, it does not attempt to provide a mitigation for existing threats to
the web security model, such as script injection or hostile intermediaries. As such,
application developers must take care to ensure applications are secured against
common and traditional attacks, such as script injection, by making use of appropriate
existing functionality such as Content Security Policy and the use of TLS.

This API includes a variety of cryptographic operations, some of which may have known
security issues when used inappropriately. Application developers should take care to
review the appropriate cryptographic literature before making use of certain algorithms,
and should avoid attempting to develop new cryptographic protocols whenever possible.

While the API in this specification provides a means to protect keys from future access
by web applications, it makes no statements as to how the actual keying material will be
stored by an implementation. As such, although a key may be inaccessible to web content,
it should not be presumed that it is inaccessible to end-users. For example, a
conforming user agent may choose to implement key storage by storing key material in
plain text on device storage. Although the user agent prevents access to the raw keying
material to web applications, any user with access to device storage may be able to
recover the key.

6. Privacy considerations

This section is non-normative.

Fingerprinting

Malicious applications may be able to fingerprint users or user agents by detecting or
enumerating the list of algorithms that are supported. This is especially true if an
implementation exposes details about users' smart cards or secure element storage, as
the combination of algorithms supported by such devices may be used to fingerprint
devices more accurately than just the particular user agent.

Tracking

If user agents permit keys to be re-used between origins, without performing any
secondary operations such as key derivation that includes the origin, then it may be
possible for two origins to collude and track a unique user by recording their ability
to access a common key.

Super-cookies

With the exception of ephemeral keys, its often desirable for applications to strongly
associate users with keys. These associations may be used to enhance the security of
authenticating to the application, such as using a key stored in a secure element as a
second factor, or may be used by users to assert some identity, such as an e-mail
signing identity. As such, these keys often live longer than their counterparts such as
usernames and passwords, and it may be undesirable or prohibitive for users to revoke
these keys.
Because of this, keys may exist longer than the lifetime of the browsing context
[HTML] and beyond the lifetime of items such as cookies, thus
presenting a risk that a user may be tracked even after clearing such data. This is
especially true for keys that were pre-provisioned for particular origins and for which
no user interaction was provided.

7. Dependencies

This specification relies on underlying specifications.

DOM

A conforming user agent MUST support at
least the subset of the functionality defined in DOM4 that this specification relies
upon; in particular, it MUST support Promises.
[DOM4]

Comparing two strings in a case-sensitive
manner means comparing them exactly, code point for code point.

When this specification says to terminate the
algorithm, the user agent must terminate the algorithm after finishing the step it
is on. The algorithm referred to is the set of specification-defined processing steps,
rather than the underlying cryptographic algorithm that may be in the midst of processing.

When this specification says to parse an ASN.1
structure, the user agent must perform the following steps:

Let data be a sequence of bytes to be parsed.

Let structure be the ASN.1 structure to be parsed.

Let exactData be an optional boolean value. If it is not supplied,
let it be initialized to true.

Parse data according to the Distinguished Encoding Rules of
X.690 (11/08), using structure as the ASN.1 structure
to be decoded.

If exactData was specified, and all of the bytes of data were
not consumed during the parsing phase, then
return an error named
DataError.

Return the parsed ASN.1 structure.

When this specification says to parse a
subjectPublicKeyInfo, the user agent must
parse an ASN.1 structure, with
data set to the sequence of bytes to be parsed, structure as the
ASN.1 structure of subjectPublicKeyInfo, as specified in RFC 5280,
and exactData set to true.

When this specification says to parse a
PrivateKeyInfo, the user agent must parse
an ASN.1 structure with data set to the sequence of bytes to be parsed,
structure as the ASN.1 structure of PrivateKeyInfo, as specified in
RFC 5208, and exactData set to true.

When this specification says to parse a JWK, the user
agent must run the following steps:

Let data be the sequence of bytes to be parsed.

Let json be the unicode string that results from interpreting
data according to UTF-8.

Let result be the result of translating json into an internal
object using the grammar specified in Section 15.12 of ECMA
262.

When this specification says to calculate the usage
intersection of two arrays, a and b the result shall be an
array containing each recognised key usage value
that appears in both a and b, in the order listed in the list of
recognised key usage values, where a value is said
to appear in an array if an element of the array exists that is a case-sensistive string
match for that value.

9. RandomSource interface

9.1. Description

The RandomSource interface represents an interface to a
cryptographically strong pseudo-random number generator seeded with truly random values.

Note

Implementations should generate cryptographically random values using
well-established cryptographic pseudo-random number generators seeded with high-quality
entropy, such as from an operating-system entropy source (e.g., "/dev/urandom"). This
specification provides no lower-bound on the information theoretic entropy present in
cryptographically random values, but implementations should make a best effort to provide
as much entropy as practicable.

Note

This interface defines a synchronous method for obtaining cryptographically random
values. While some devices and implementations may support truly random cryptographic
number generators or provide interfaces that block when there is insufficient entropy,
implementations are discouraged from using these sources when implementing
getRandomValues, both for performance and to avoid depleting the system of entropy.
Instead, these sources should be used to seed a cryptographic pseudo-random number
generator that can then return suitable values efficiently.

9.2. Methods and Parameters

9.2.1. The getRandomValues method

The getRandomValues
method generates cryptographically random values. It must act as follows:

If array is not of an integer type (i.e., Int8Array, Uint8Array,
Int16Array, Uint16Array, Int32Array, or Uint32Array), throw a
TypeMismatchError and
terminate the algorithm.

11. KeyAlgorithm interface

11.1. Description

This section is non-normative

The KeyAlgorithm interface is a supplemental interface
used to reflect the static, public properties of a Key back to an
application. These properties can be used for determination of strength (e.g.: an
attribute that indicates the size of the key or the parameters of its creation) as well
as for protocol negotiations (e.g.: a particular instance of an inner hash).

12.1. Description

This section is non-normative

This specification provides a uniform interface for many different kinds of keying
material managed by the user agent. This may include keys that have been generated by
the user agent, derived from other keys by the user agent, imported to the user agent
through user actions or using this API, pre-provisioned within software or hardware to
which the user agent has access or made available to the user agent in other ways. The
term key refers broadly to any keying material including actual keys for cryptographic
operations and secret values obtained within key derivation or exchange operations.

The Key object is not required to directly interface with the underlying key storage
mechanism, and may instead simply be a reference for the user agent to understand how to
obtain the keying material when needed, eg. when performing a cryptographic operation.

12.2. Key interface data types

KeyType

The type of a key. The recognized key type values
are "public", "private" and "secret".
Opaque keying material, including that used for symmetric algorithms, is represented by
"secret", while keys used as part of asymmetric algorithms composed of
public/private keypairs will be either "public" or "private".

KeyUsage

A type of operation that may be performed using a key. The
recognized key usage values are
"encrypt",
"decrypt",
"sign",
"verify",
"deriveKey",
"deriveBits",
"wrapKey" and
"unwrapKey".

12.3. Key interface members

type

The type of the underlying key.

extractable

Whether or not the raw keying material may be exported by the application.

Let the following attributes of output be equal to the value obtained by
invoking the internal structured clone algorithm recursively, using the corresponding
attribute on input as the new "input" argument and
memory as the new "memory" argument:

Let output refer to the same underlying cryptographic material and
cryptographic material key storage of input.

Note

Implementation Note: When performing the structured clone algorithm for
a Key object, it is important that the underlying cryptographic key
material not be exposed to a JavaScript implementation. Such a situation may arise if an
implementation fails to implement the structured clone algorithm correctly, such as by
allowing a Key object to be serialized as part of a structured clone
implementation, but then deserializing it as a DOMString, rather than as a
Key object.

ISSUE-35:
The specification for wrapKey/unwrapKey does not specify how authors that do not trust
the execution environment may indicate required attributes for keys that are
unwrapped. An example is unwrapping a key with a non-extractable key, marking
the newly unwrapped key as non extractable, and then further indicating that all
keys unwrapped with the newly unwrapped key are also non-extractable.

14.1. Description

This section is non-normative.

The SubtleCrypto interface provides a set of
methods for dealing with low-level cryptographic primitives and algorithms. It is
named SubtleCrypto to reflect the fact that many of these algorithms
have subtle usage requirements in order to provide the required algorithmic
security guarantees.

For example, the direct use of an unauthenticated encryption scheme, such as
AES in counter mode, gives potential attackers the ability to
manipulate bits in the output by manipulating bits in the input, compromising the
integrity of the message. However, AES-CTR can be used securely in combination
with other cryptographic primitives, such as message authentication codes, to ensure
the integrity of the protected message, but only when the message authentication
code is constructed over the encrypted message and IV.

Developers making use of the SubtleCrypto interface are expected to be aware of the
security concerns associated with both the design and implementation of the various
algorithms provided. The raw algorithms are provided in order to allow developers
maximum flexibility in implementing a variety of protocols and applications, each of
which may represent the composition and security parameters in a unique manner that
necessitate the use of the raw algorithms.

14.2. Data Types

KeyFormat

Specifies a serialization format for a key. The recognized key format values are:

Let length be the result of executing the get key length
algorithm specified by normalizedDerivedKeyAlgorithm using
derivedKeyType.

Let secret be the result of executing the derive bits operation
specified by normalizedAlgorithm using
key, algorithm and length.

Let result be the result of executing the import key operation
specified by normalizedDerivedKeyAlgorithm using "raw" as
format, secret as keyData,
derivedKeyType as algorithm and using
extractable and usages.

Execute resolver's resolve(value) algorithm, with
result as the value argument.

14.3.8. The deriveBits method

When invoked, deriveBitsMUST perform the following steps:

Let algorithm, baseKey and length,
be the algorithm,
baseKey and length
parameters passed to the
deriveBits method,
respectively.

Let promise be a new Promise object and resolver its
associated resolver object.

Return promise and asynchronously perform the remaining steps.

If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value) algorithm, with
the returned error as the value argument and then
terminate the algorithm.

Let result be the Key object that
results from performing the import key operation specified by
normalizedAlgorithm using keyData,
algorithm,
format, extractable and usages.

Execute resolver's resolve(value) algorithm, with
result as the value argument.

Editorial note

Bug 24963 -
There is an open question as to whether/how to support importing
keys when format is jwk. As currently specified, it is a
JSON-encoded Javascript object, converted to a UTF-8 byte sequence, with the
raw bytes provided via CryptoOperationData. A separate
proposal exists to handle this via IDL, permitting importing JavaScript
objects directly when importing with jwk.

Let result be the result of performing the export key operation
specified by the algorithm
attribute of key using key and format.

Execute resolver's resolve(value) algorithm, with
result as the value argument.

Editorial note

Bug 24963 -
There is an open question as to whether/how to support exporting
keys when format is jwk. As currently specified, the result
is a JSON-encoded Javascript object, converted to a UTF-8 byte
sequence, with the raw bytes provided via an ArrayBuffer. A separate
proposal exists to return an actual Javascript object when exporting
with jwk.

14.3.11. The wrapKey method

When invoked, the wrapKey method MUST perform the following steps:

Let format, key, wrappingKey and
algorithm be the format, key,
wrappingKey and wrapAlgorithm parameters passed to the
wrapKey method,
respectively.

Let promise be a new Promise object and resolver its
associated resolver object.

Return promise and asynchronously perform the remaining steps.

If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value) algorithm, with
the returned error as the value argument and then
terminate the algorithm.

Perform type mapping as specified in [WEBIDL] for
format, key and wrappingKey.

Let normalizedAlgorithm be the result of
normalizing algorithm
to Algorithm.

Let bytes be the result of performing the export key operation specified
the algorithm
attribute of key using key and format.

Note

This note is non-normative.

The key wrapping operations for some algorithms place constraints on the payload
size. For example AES-KW requires the payload to be a multiple of 8 bytes in
length and RSA-OAEP places a restriction on the length. For key formats that
offer flexibility in serialization of a given key (for example JWK),
implementations may choose to adapt the serialization to the constraints of
the wrapping algorithm.

If normalizedAlgorithm supports the wrap key operation:

Let result be the result of performing the wrap key operation
specified by normalizedAlgorithm using algorithm,
wrappingKey
as key and bytes as plaintext.

Otherwise, if normalizedAlgorithm supports the encrypt operation:

Let result be the result of performing the encrypt operation
specified by normalizedAlgorithm using algorithm,
wrappingKey
as key and bytes as plaintext.

Let result be the result of performing the import key operation
specified by normalizedKeyAlgorithm using
unwrappedKeyAlgorithm as algorithm, format,
usages
and extractable and with
bytes as keyData.

Execute resolver's resolve(value) algorithm, with
result as the value argument.

14.4. Exceptions

The methods of the SubtleCrypto interface return errors
by calling the reject handler of the returned promise with a
DOMException. The following DOMException types from
[DOM4] are used with messages as shown in the following table:

Type

Message (optional)

NotSupportedError

The algorithm is not supported

SyntaxError

A required parameter was missing our out-of-range

InvalidStateError

The requested operation is not value for the current state of the provided key.

InvalidAccessError

The requested operation is not valid for the provided key

The following new DOMException types are defined by this specification:

Type

Message (optional)

UnknownError

The operation failed for an unknown transient reason (e.g. out of memory)

DataError

Data provided to an operation does not meet requirements

OperationError

The operation failed for an operation-specific reason

When this specification says to
return an error named error,
where error
is one of the above error names, the user agent must return a
DOMException with name error and message as
defined in the above two tables.

15.1. Description

16. BigInteger

IDL

typedef Uint8Array BigInteger;

The BigInteger typedef is a Uint8Array that
holds an arbitrary magnitude unsigned integer in big-endian order. Values read from
the API SHALL have minimal typed array length (that is, at most 7 leading zero bits,
except the value 0 which shall have length 8 bits). The API SHALL accept values with
any number of leading zero bits, including the empty array, which represents zero.

Note

Implementation Note: Since the integer is unsigned, the highest order bit
is NOT a sign bit. Implementors should take care when mapping to big integer
implementations that expected signed integers.

17. KeyPair

The KeyPair interface represents an
asymmetric key pair that is comprised of both public and private keys.

18. Algorithms

Editorial note

Note: All algorithms listed should be considered as "features at risk",
barring implementors adopting them. Their inclusion in the Last Call Working Draft
reflects requests for their inclusion by members of the community, and are
included as an exercise to ensure the robustness of the API defined in this
specification.

As such, the list of algorithms, and the recommendations, may be significantly
altered in future revisions.

18.2. Recommended algorithms

This section is non-normative

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.

However, in order to promote interoperability for developers, there are a number of
recommended algorithms. The recommended algorithms are:

Results will be provided in the form of test-cases between implementations, by the time the this document reaches Candidate Recommendation.

18.3. Defining an algorithm

Each algorithm that is to be exposed via the Web Cryptography API
SHOULD be registered via the Web Cryptography working group,
and MUST include all of the following details. Algorithms
that are not registered via these means, but are exposed via this API,
MUST be processed as if the sections had been defined.

18.3.1. Recognized algorithm name

Each registered algorithm MUST have a canonical name
for which applications can refer to the algorithm. The canonical name
MUST contain only ASCII characters and
MUST NOT equal any other canonical name or
algorithm alias when every character in both names
are converted to lower case.

18.3.2. Supported operations

Each registered algorithm MUST define the operations
that it supports.

18.3.3. Algorithm-specific parameters

Each registered algorithm MUST define the expected
parameters, if any, that should be exposed via the Algorithm
dictionary for every supported operation.

18.3.4. Algorithm results

Each registered algorithm MUST define the contents
of the result of performing the underlying cryptographic operation for every
supported operation.

18.3.5. Algorithm aliases

Each registered algorithm MAY define one or more aliases
that may define a fully normalized Algorithm object.

If usages contains an entry which is not
"encrypt", "decrypt",
"wrapKey" or "unwrapKey",
then return an error named
DataError.

Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the
modulusLength member of
normalizedAlgorithm and RSA public exponent equal to the
publicExponent member of
normalizedAlgorithm.

If the algorithm object identifier field of the
algorithm AlgorithmIdentifier field of spki
is not equivalent to the rsaEncryption OID defined in
Section 2.3.1 of RFC 3279,
then return an error named
DataError.

Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo field of spki,
structure as the RSAPublicKey structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.

If the algorithm object identifier field of the
privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field
of privateKeyInfo is not equivalent to the
rsaEncryption OID defined in Section 2.3.1 of
RFC 3279,
then return an error named
DataError.

Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey field of privateKeyInfo,
structure as the RSAPrivateKey structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.

Let result be the result of encoding a privateKeyInfo
with the following properties:

Set the version field to 0.

Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifier ASN.1 type with the
following properties:

Set the algorithm field to the OID
1.2.840.113549.1.1

Set the params field to the ASN.1 type NULL.

Set the privateKey field to the result of
DER-encoding an RSAPrivateKey ASN.1 type, as defined
in RFC 3447, Appendix A.1.2, that
represents the RSA private key identified by key

Editorial note

RFC 5208 specifies that the encoding of
this field should be BER encoded in Section 5 (as a "for
example"). However, to avoid requiring WebCrypto implementations
support BER-encoding and BER-decoding, only DER encodings
are produced or accepted.

If format is "jwk":

Let jwk be a new internal object.

Set the kty property of jwk to the string
"RSA".

Set the alg property of jwk to the string
"RSA1_5".

Set the properties n and e of jwk
according to the corresponding definitions in JSON Web
Algorithms, Section 6.3.1.

Set the properties named d, p,
q, dp, dq, and
qi of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.

If the underlying RSA private key represented by
key is represented by more than two primes, set the
member named oth of jwk according to
the corresponding definition in JSON Web
Algorithms, Section 6.3.2.7

18.5.6. Operations

Perform the signature generation operation defined in Section 8.2 of
[RFC3447] with the key represented by
key as the signer's private key and the contents of
message as M and using the hash function specified in
the hash attribute of the
algorithm attribute of key as the
Hash option for the EMSA-PKCS1-v1_5 encoding method.

Perform the signature verification operation defined in Section 8.2 of
[RFC3447] with the key represented by
key as the signer's RSA public key and the contents of
message as M and signature as S
and using the hash function specified in the
hash attribute of the
algorithm attribute of
key as the Hash option for the EMSA-PKCS1-v1_5 encoding method.

Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the
modulusLength attribute of
normalizedAlgorithm and RSA public exponent equal to the
publicExponent attribute of
normalizedAlgorithm.

Set hash to the name member of the hash member of
normalizedAlgorithm.

Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo field of spki,
structure as the RSAPublicKey structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.

Set hash to the name member of the hash member of
normalizedAlgorithm.

Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey field of privateKeyInfo,
structure as the RSAPrivateKey structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.

Let result be the result of encoding a privateKeyInfo
with the following properties:

Set the version field to 0.

Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifier ASN.1 type with the
following properties:

Set the algorithm field to the OID
1.2.840.113549.1.1

Set the params field to the ASN.1 type NULL.

Set the privateKey field to the result of
DER-encoding an RSAPrivateKey ASN.1 type, as defined
in RFC 3447, Appendix A.1.2, that
represents the RSA private key identified by key

Editorial note

RFC 5208 specifies that the encoding of
this field should be BER encoded in Section 5 (as a "for
example"). However, to avoid requiring WebCrypto implementations
support BER-encoding and BER-decoding, only DER encodings
are produced or accepted.

Set the fields named d, p,
q, dp, dq, and
qi of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.

If the underlying RSA private key represented by
key is represented by more than two primes, set the
field named oth of jwk according to
the corresponding definition in JSON Web
Algorithms, Section 6.3.2.7

Perform the signature generation operation defined in Section 8.1 of [RFC3447] with the key represented by key
as the signer's private key, K, and the contents of
message as the message to be signed, M, and using the
hash function specified by the
hash attribute of the
algorithm attribute of key
as the Hash option, MGF1 (defined in Section B.2.1 of
[RFC3447]) as the MGF option and
the saltLength member of
normalizedAlgorithm as the salt length option for the EMM-PSS-ENCODE
operation.

Perform the signature verification operation defined in Section 8.1 of [RFC3447] with the key represented by key
as the signer's RSA public key and the contents of message as
M and the contents of signature as S and using
the hash function specified by the
hash attribute of the
algorithm attribute of key as the
Hash option, MGF1 (defined in Section B.2.1 of
[RFC3447]) as the MGF option and the
saltLength member of
normalizedAlgorithm as the salt length option for the
EMSA-PSS-VERIFY operation.

Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the
modulusLength member of
normalizedAlgorithm and RSA public exponent equal to the
publicExponent member of
normalizedAlgorithm.

If the parameters field of the
maskGenAlgorithm field of params is not
an instance of the HashAlgorithm ASN.1 type that is
identical in content to the hashAlglorithm field of
params, return an
error named NotSupportedError.

Set hash to the name member of the hash member of
normalizedAlgorithm.

Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo field of spki,
structure as the RSAPublicKey structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.

If the parameters field of the
maskGenAlgorithm field of params is not
an instance of the HashAlgorithm ASN.1 type that is
identical in content to the hashAlglorithm field of
params, return an
error named NotSupportedError.

Set hash to the name member of the hash member of
normalizedAlgorithm.

Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey field of privateKeyInfo,
structure as the RSAPrivateKey structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.

Set the params field to an instance of the
HashAlgorithm ASN.1 type that is
identical to the hashAlgorithm field.

Set the saltLength field to the length in
octets of the digest algorithm identified by the name attribute of the hash attribute
of the algorithm
attribute of key.

Set the privateKey field to the result of
DER-encoding an RSAPrivateKey ASN.1 type, as defined
in RFC 3447, Appendix A.1.2, that
represents the RSA private key identified by key

Editorial note

RFC 5208 specifies that the encoding of
this field should be BER encoded in Section 5 (as a "for
example"). However, to avoid requiring WebCrypto implementations
support BER-encoding and BER-decoding, only DER encodings
are produced or accepted.

If format is "jwk":

Let jwk be a new internal object.

Set the kty field of jwk to the string
"RSA".

Let hash be the name
attribute of the hash
attribute of the algorithm attribute
of key.

Set the fields named d, p,
q, dp, dq, and
qi of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.

If the underlying RSA private key represented by
key is represented by more than two primes, set the
field named oth of jwk according to
the corresponding definition in JSON Web
Algorithms, Section 6.3.2.7

Perform the encrytion operation defined in Section 7.1 of [RFC3447] with the key represented by key
as the recipient's RSA public key, the contents of plaintext as the
message to be encrypted, M and the
label member of
normalizedAlgorithm as the label, L, and with the hash
function specified by the
hash attribute of the
algorithm attribute of key as the
Hash option and MGF1 (defined in Section B.2.1 of
[RFC3447]) as the MGF option.

Perform the decryption operation defined in Section 7.1 of [RFC3447] with the key represented by key
as the recipient's RSA private key, the contents of ciphertext as
the cipertext to be decrypted, C, and the
label member of
normalizedAlgorithm as the label, L, and with the hash
function specified by the
hash attribute of the
algorithm attribute of key as the
Hash option and MGF1
(defined in Section B.2.1 of [RFC3447]) as
the MGF option.

Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the
modulusLength member of
normalizedAlgorithm and RSA public exponent equal to the
publicExponent member of
normalizedAlgorithm.

If the parameters field of the
maskGenAlgorithm field of params is not
an instance of the HashAlgorithm ASN.1 type that is
identical in content to the hashAlglorithm field of
params, return an
error named NotSupportedError.

Set hash to the name member of the hash member of
normalizedAlgorithm.

Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo field of spki,
structure as the RSAPublicKey structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.

If the parameters field of the
maskGenAlgorithm field of params is not
an instance of the HashAlgorithm ASN.1 type that is
identical in content to the hashAlglorithm field of
params, return an
error named NotSupportedError.

Set hash to the name member of the hash member of
normalizedAlgorithm.

Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey field of privateKeyInfo,
structure as the RSAPrivateKey structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.

Set the params field to an instance of the
HashAlgorithm ASN.1 type that is
identical to the hashAlgorithm field.

Set the privateKey field to the result of
DER-encoding an RSAPrivateKey ASN.1 type, as defined
in RFC 3447, Appendix A.1.2, that
represents the RSA private key identified by key

Editorial note

RFC 5208 specifies that the encoding of
this field should be BER encoded in Section 5 (as a "for
example"). However, to avoid requiring WebCrypto implementations
support BER-encoding and BER-decoding, only DER encodings
are produced or accepted.

If format is "jwk":

Let jwk be a new internal object.

Set the kty field of jwk to the string
"RSA".

Set the alg field of jwk to the string
RSA-OAEP.

Set the fields n and e of jwk
according to the corresponding definitions in JSON Web
Algorithms, Section 6.3.1.

Set the fields named d, p,
q, dp, dq, and
qi of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.

If the underlying RSA private key represented by
key is represented by more than two primes, set the
field named oth of jwk according to
the corresponding definition in JSON Web
Algorithms, Section 6.3.2.7

Let M be the result of performing the digest operation specified by
hashAlgorithm using message.

Let Q be the ECDSA public key associated with key.

Let params be the EC domain parameters associated with
key.

Perform the ECDSA verifying process, as specified in X9.62, Section 7.4, with M as the received
message, signatire as the received signature and using
params as the EC domain parameters, and
Q as the public key.

Let result be a boolean indicating whether or not the purported
signature is valid, with true indicating the signature is valid
and false indicating it is invalid.

Return result.

Generate Key

Let normalizedAlgorithm be the result of
normalizing algorithm
to EcKeyGenParams.

If the algorithm object identifier field of the
algorithm AlgorithmIdentifier field of spki is
not equal to the id-ecPublicKey
object identifier defined in RFC 5480,
then return an error named
DataError.

If the parameters field of the algorithm
AlgorithmIdentifier field of spki is absent,
then return an error named
DataError.

Let params be the parameters field of the
algorithm AlgorithmIdentifier field of spki.

If the algorithm object identifier field of the
privateKeyAlgorithm PrivateKeyAlgorithm field of
privateKeyInfo is not equal to the
id-ecPublicKey object identifier defined in RFC 5480,
then return an error named
DataError.

If the parameters field of the
privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field
of privateKeyInfo is not present,
then return an error named
DataError.

Let params be the parameters field of the
privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field
of privateKeyInfo.

Let ecPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the privateKey field
of privateKeyInfo, structure as the ASN.1
ECPrivateKey structure specified in Section 3 of RFC 5915, and exactData set to true.

If the parameters field of ecPrivateKey is
present, and is not an instance of the namedCurve ASN.1
type defined in RFC 5480, or does not contain
the same object identifier as the parameters field of the
privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field
of privateKeyInfo,
then return an error named
DataError.

Let key be a new Key object that
represents the Elliptic Curve private key identified by performing the
conversion steps defined in Section 3 of RFC
5915.

Let the namedCurve be the object identifier
secp521r1 defined in RFC
5480

Set the subjectPublicKey field to the octet string that
represents the Elliptic Curve public key identified by
key according to the encoding rules specified in
Section 2.2 of RFC 5480 and using the
uncompressed form.

Let the namedCurve be the object identifier
secp521r1 defined in RFC
5480

Set the privateKey field to the result of DER-encoding
an instance of the ECPrivateKey structure defined in
Section 3 of RFC 5915 for the Elliptic
Curve private key represented by key and that conforms
to the following:

The parameters field is present, and is equivalent
to the parameters field of the
privateKeyAlgorithm field of this
PrivateKeyInfo ASN.1 structure.

The publicKey field is present and represents the
Elliptic Curve public key associated with the Elliptic Curve
private key represented by key.

OPEN ISSUE: The import/export of JWK ignores the "alg" field, because it does not
provide a 1:1 mapping between ECDSA (which choses the hash at sign/verify time,
because it is safe to do so) and the JWS alg (which incorporates the hash algorithm).

18.9. ECDH

18.9.1. Description

This describes using Elliptic Curve Diffie-Hellman (ECDH) for key generation and key
agreement, as specified by X9.63.

If the algorithm object identifier field of the
algorithm AlgorithmIdentifier field of spki is
not equal to the id-ecPublicKey or id-ecDH
object identifiers defined in RFC 5480,
then return an error named
DataError.

If the algorithm object identifier field of the
privateKeyAlgorithm PrivateKeyAlgorithm field of
privateKeyInfo is not equal to the
id-ecPublicKey or id-ecDH object identifiers
defined in RFC 5480,
return an error named
DataError.

If the parameters field of the
privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field
of privateKeyInfo is not present,
return an error named
DataError.

Let params be the parameters field of the
privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field
of privateKeyInfo.

Let ecPrivateKey be the result of performing the
parse an ASN.1 structure
algorithm, with data as the privateKey field
of privateKeyInfo, structure as the ASN.1
ECPrivateKey structure specified in Section 3 of
RFC 5915, and exactData set to true.

If the parameters field of ecPrivateKey is
present, and is not an instance of the namedCurve ASN.1
type defined in RFC 5480, or does not contain
the same object identifier as the parameters field of the
privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field
of privateKeyInfo,
return an error named
DataError.

Let key be a new Key object that
represents the Elliptic Curve private key identified by performing the
conversion steps defined in Section 3 of RFC
5915.

Let the namedCurve be the object identifier
secp521r1 defined in RFC
5480

Set the subjectPublicKey field to the octet string that
represents the Elliptic Curve public key identified by
key according to the encoding rules specified in
Section 2.2 of RFC 5480 and using the
uncompressed form.

Let the namedCurve be the object identifier
secp521r1 defined in RFC
5480

Set the privateKey field to the result of DER-encoding
an instance of the ECPrivateKey structure defined in
Section 3 of RFC 5915 for the Elliptic
Curve private key represented by key and that conforms
to the following:

The parameters field is present, and is equivalent
to the parameters field of the
privateKeyAlgorithm field of this
PrivateKeyInfo ASN.1 structure.

The publicKey field is present and represents the
Elliptic Curve public key associated with the Elliptic Curve
private key represented by key.

18.10.3. AesCtrParams dictionary

IDL

dictionary AesCtrParams : Algorithm {
// The initial value of the counter block. counter MUST 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.
CryptoOperationData counter;
// The length, in bits, of the rightmost part of the counter block
// that is incremented.
[EnforceRange] octet length;
};

Let ciphertext be the result of performing the CTR Encryption
operation described in Section 6.5 of
NIST SP 800-38A [SP800-38A] using AES as the block
cipher, the contents of the counter member of
normalizedAlgorithm as the initial
value of the counter block,
the length member of
normalizedAlgorithm as the input parameter
m to the standard counter block incrementing functon defined
in Appendix B.1 of NIST SP 800-38A [SP800-38A] and
plaintext as the input plaintext.

Return ciphertext.

Decrypt

Let normalizedAlgorithm be the result of
normalizing algorithm
to AesCtrParams.

Let plaintext be the result of performing the CTR Decryption
operation described in Section 6.5 of
NIST SP 800-38A [SP800-38A] using AES as the block
cipher, the contents of the counter member of
normalizedAlgorithm as the initial
value of the counter block,
the length member of
normalizedAlgorithm as the input parameter
m to the standard counter block incrementing functon defined
in Appendix B.1 of NIST SP 800-38A [SP800-38A] and
ciphertext as the input ciphertext.

Return plaintext.

Generate Key

Let normalizedAlgorithm be the result of
normalizing algorithm
to AesKeyGenParams.

18.11. AES-CBC

18.11.1. Description

This section is non-normative.

The "AES-CBC" algorithm identifier is used to perform
encryption and decryption using AES in Cipher Block Chaining mode,
as described in NIST SP 800-38A [SP800-38A].

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 [RFC2315].

Let padded-plaintext be the result of adding padding octets to
ciphertext according to the procedure defined in Section 10.3
of RFC 2315 [RFC2315], step 2, with a value of
k of 16.

Let ciphertext be the result of performing the CBC Encryption
operation described in Section 6.2 of
NIST SP 800-38A [SP800-38A] using AES as the block
cipher, the contents of the iv member of
normalizedAlgorithm as the IV input parameter and
padded-plaintext as the input plaintext.

Return ciphertext.

Decrypt

Let normalizedAlgorithm be the result of
normalizing algorithm
to AesCbcParams.

Let padded-plaintext be the result of performing the CBC Decryption
operation described in Section 6.2 of
NIST SP 800-38A [SP800-38A] using AES as the block
cipher, the contents of the iv member of
normalizedAlgorithm as the IV input parameter and
ciphertext as the input ciphertext.

Let p be the value of the last octet of padded-plaintext.

If p is zero or greater than 16, or if any of the last p
octets of padded-plaintext have a value which is not p,
then return an error named
DataError.

Let plaintext be the result of removing p octents from
the end of padded-plaintext.

Return plaintext.

Generate Key

Let normalizedAlgorithm be the result of
normalizing algorithm
to AesKeyGenParams.

18.12.4. Operations

Let mac be the result of performing the MAC Generation
operation described in Section 6.2 of
NIST SP 800-38B [SP800-38B] using AES as the block
cipher, length as the value of the MAC length parameter,
Tlen, and message as the message, M.

Return mac.

Verify

Let normalizedAlgorithm be the result of
normalizing algorithm
to AesCmacParams.

Let length equal the length
member of normalizedAlgorithm, if present, and 128 otherwise.

Let ouput be the result of performing the MAC Verification
operation described in Section 6.3 of
NIST SP 800-38B [SP800-38B] using AES as the block
cipher, length as the value of the MAC length parameter,
Tlen, message as the message, M and
signature as the received MAC, T'.

Return true if output is VALID and false otherwise.

Generate Key

Let normalizedAlgorithm be the result of
normalizing algorithm
to AesKeyGenParams.

Let additionalData be the contents of the
additionalData member
of normalizedAlgorithm if present and not null and the empty
octet string otherwise.

Let C and T be the outputs that result from performing
the Authenticated Encryption Function described in Section 7.1 of
NIST SP 800-38D [SP800-38D] using AES as the block
cipher, the contents of the iv member of
normalizedAlgorithm as the IV input parameter,
additionalData as the A input parameter,
tagLength as the t pre-requisite and
plaintext as the input plaintext.

Let actualCiphertext be the result of removing the last tagLength bits
from ciphertext.

Let additionalData be the contents of the
additionalData member
of normalizedAlgorithm if present and not null and the empty
octet string otherwise.

Perform the Authenticated Decryption Function described in Section 7.2 of
NIST SP 800-38D [SP800-38D] using AES as the block
cipher, the contents of the iv member of
normalizedAlgorithm as the IV input parameter,
additionalData as the A input parameter,
tagLength as the t pre-requisite,
actualCiphertext as the input ciphertext, C and
tag as the authentation tag, T.

If the result of the algorithm is the indication of inauthenticity,
"FAIL":

Let ciphertext be the result of performing the CFB Encryption
operation described in Section 6.3 of
NIST SP 800-38A [SP800-38A] using AES as the block
cipher, the contents of the iv member of
normalizedAlgorithm as the IV input parameter, the
value 8 as the input parameter s and
plaintext as the input plaintext.

Return ciphertext.

Decrypt

Let normalizedAlgorithm be the result of
normalizing algorithm
to AesCfbParams.

Let plaintext be the result of performing the CFB Decryption
operation described in Section 6.3 of
NIST SP 800-38A [SP800-38A] using AES as the block
cipher, the contents of the iv member of
normalizedAlgorithm as the IV input parameter, the
the value 8 as the input parameter s and
ciphertext as the input ciphertext.

Return plaintext.

Generate Key

Let normalizedAlgorithm be the result of
normalizing algorithm
to AesKeyGenParams.

18.15.3. Operations

Let ciphertext be the result of performing the Key Wrap
operation described in Section 2.2.1 of [RFC3394]
with plaintext as the plaintext to be wrapped and using the default
Initial Value defined in Section 2.2.3.1 of the same document.

Return ciphertext.

Unwrap Key

Let plaintext be the result of performing the Key Unwrap
operation described in Section 2.2.2 of [RFC3394] with
ciphertext as the input ciphertext and using the default Initial
Value defined in Section 2.2.3.1 of the same document.

18.16.4. HmacKeyAlgorithm interface

18.16.5. HmacKeyGenParams dictionary

IDL

dictionary HmacKeyGenParams : Algorithm {
// The inner hash function to use.
AlgorithmIdentifier hash;
// 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.
[EnforceRange] unsigned long length;
};

18.16.6. HmacDerivedKeyParams dictionary

IDL

dictionary HmacDerivedKeyParams : HmacImportParams {
// 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.
[EnforceRange] unsigned long length;
};

18.16.7. Operations

Sign

Let mac be the result of performing the MAC Generation
operation described in Section 4 of
[FIPS PUB 198-1] using the key represented by key,
the hash function identified by the
hash attribute of the
algorithm attribute of key and
message as the input data text.

Return mac.

Verify

Let mac be the result of performing the MAC Generation
operation described in Section 4 of
[FIPS PUB 198-1] using the key represented by key,
the hash function identified by the
hash attribute of the
algorithm attribute of key and
message as the input data text.

Return true if mac is equal to signature and false
otherwise.

Generate Key

Let normalizedAlgorithm be the result of
normalizing algorithm
to HmacKeyGenParams.

Perform the Diffie Hellman Phase II algorithm as specified in
Section 8 of [PKCS #3]
with key as the DH private value x and the
Diffie Hellman public value represented by the
public member of
normalizedAlgorithm as the other's public value PV'.

If the algorithm object identifier field of the
algorithm AlgorithmIdentifier field of spki is not
equivalent to the dhKeyAgreement OID defined in Section 9
of [PKCS #3],
then return an error named
DataError.

If the parameters field of the algorithm
AlgorithmIdentifier field of spki is absent,
then return an error named
DataError.

Let params be the parameters field of the
algorithm AlgorithmIdentifier field of spki.

If the algorithm object identifier field of the
algorithm AlgorithmIdentifier field of
privateKeyInfo is not
equivalent to the dhKeyAgreement OID defined in Section 9
of [PKCS #3],
then return an error named
DataError.

If the parameters field of the
privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field of
privateKeyInfo is absent,
then return an error named
DataError.

Let params be the parameters field of the
privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field of
privateKeyInfo.

18.19.2. Registration

18.19.3. ConcatParams dictionary

IDL

dictionary ConcatParams : Algorithm {
// The digest method to use to derive the keying material.
AlgorithmIdentifier hash;
// A bit string corresponding to the AlgorithmId field of the OtherInfo parameter.// The AlgorithmId indicates how the derived keying material will be parsed and for which// algorithm(s) the derived secret keying material will be used.
CryptoOperationData algorithmId;
// A bit string that corresponds to the PartyUInfo field of the OtherInfo parameter.
CryptoOperationData partyUInfo;
// A bit string that corresponds to the PartyVInfo field of the OtherInfo parameter.
CryptoOperationData partyVInfo;
// An optional bit string that corresponds to the SuppPubInfo field of the OtherInfo parameter.
CryptoOperationData? publicInfo;
// An optional bit string that corresponds to the SuppPrivInfo field of the OtherInfo parameter.
CryptoOperationData? privateInfo;
};

18.19.4. Operations

Derive Bits

Let normalizedAlgorithm be the result of
normalizing algorithm
to ConcatParams.

Let secret be the result of performing the Concatenation Key
Derivation Funtion defined in Section 5.8.1 of
[SP800-56A] with length as
keydatalen, the hash function identified by the
hash member of
normalizedAlgorithm as H, the
algorithmId member of
normalizedAlgorithm as AlgorithmID, the
partyUInfo member of
normalizedAlgorithm as PartyUInfo, the
partyVInfo member of
normalizedAlgorithm as PartyVInfo, the
publicInfo member of
normalizedAlgorithm, if present and not null, as
publicInfo and the
privateInfo member of
normalizedAlgorithm, if present and not null, as
privateInfo.

18.20. HKDF-CTR

18.20.1. Description

This section is non-normative.

The "HKDF-CTR" algorithm identifier is used to
perform key derivation using the extraction-then-expansion approach described in
NIST SP 800-56C[SP800-56C], using HMAC in counter mode,
as described in Section 5.1 of NIST SP 800-108
[SP800-108].

18.20.2. Registration

18.20.3. HkdfCtrParams dictionary

IDL

dictionary HkdfCtrParams : Algorithm {
// The algorithm to use with HMAC (eg: SHA-256)
AlgorithmIdentifier hash;
// A bit string that corresponds to the label that identifies the purpose for the derived keying material.
CryptoOperationData label;
// A bit string that corresponds to the context of the key derivation, as described in Section 5 of NIST SP 800-108 [SP800-108]
CryptoOperationData context;
};

Editorial note

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 behaviour be of a user agent that does not support explicit salt
values (is it conforming or non-conforming?)

18.21. PBKDF2

18.21.1. Description

This section is non-normative.

The "PBKDF2" algorithm identifier is used to
perform key derivation using the PKCS#5 password-based key
derivation function version 2.0, as defined in
[RFC2898] using HMAC as the pseudo-random function.

18.21.3. Pbkdf2Params dictionary

In the above snippet, password is an optional field. The intent is
that conforming user agents MAY support applications
that wish to use PBKDF2 by providing password entry via an un-spoofable (by the
web application) UI.

18.21.4. Operations

Derive bits

Let normalizedAlgorithm be the result of
normalizing algorithm
to Pbkdf2Params.

Let prf be the MAC Generation function described in Section 4 of
[FIPS PUB 198-1] using the hash function
described by the hash member of
normalizedAlgorithm.

Let result be the result of performing the PBKDF2 operation defined
in Section 5.2 of [RFC2898] using prf as the
pseudo-random function, PRF, the password represented by
key as the password, P, the contents of the
salt attribute of
normalizedAlgorithm as the salt, S, the value of the
iterations attribute of
normalizedAlgorithm as the iteration count, c, and
length divided by 8 as the intended key length, dkLen.

19. Algorithm normalizing rules

The AlgorithmIdentifier typedef
permits algorithms to be specified as either an Algorithm
dictionary or a DOMString. The DOMString
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.

Additionally, many algorithms define a subclass of the
Algorithm type. As a result WebIDL type mapping to the
correct subclass must be performed at the appropriate time.

When this specification says that a value algorithm be
normalized to type the user agent must
perform the following steps:

Let result be the result of mapping objectAlgorithm to
type as specified in [WEBIDL].

If a member, memberName, of type has a type
that is a union of DOMString and a type,
memberType, that is either Algorithm or a
subclass of Algorithm and if the memberName
member of result is present and has type
DOMString, then
replace memberName in result with the result of
normalizing the memberName member of
result to memberType.

21. IANA Considerations

21.1. JSON Web Signature and Encryption Algorithms Registration

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
'Implementation Requirements' field in the template refers to use with JSON Web
Signature and JSON Web Encryption specifically, in which case use of unauthenticated
encryption is prohibited.

The handling of "id-RSASSA-PSS" and "id-RSAES-OAEP" are tricky.
RFC 5756 recommends implementations should not include parameters
when PSS is used with a subjectPublicKeyInfo, and MUST NOT include parameters when OAEP
is used. However, when OAEP is used as part of a key transport (as an AlgorithmIdentifier),
implementations MUST include the parameters.

The natural conflict is in deciding when a key is being exported as part of a
subjectPublicKeyInfo (which is what "spki" implies) and when it's being used as an
algorithmIdentifier for transport.

C. Mapping between Algorithm and PKCS#8 PrivateKeyInfo

The following section is non-normative. Refer to algorithm-specific sections for the
normative requirements of importing and exporting PKCS#8 PrivateKeyInfo.