Web Crypto Spec Feedback on Dictionaries as return type properties

While reviewing the latest editor's draft of the Web Crypto API [1], we noticed a potential problem that might we worth quickly addressing before the spec advances to last call. 

Web Crypto defines an "Algorithm" as a dictionary type [2]. The Algorithm dictionary is useful for specifying multiple input parameters to a variety of functions in a natural, JavaScript-friendly way.

The Algorithm dictionaries are also available in CryptoOperation [3] and Key [4] to allow for inspection of the source algorithm information from which those objects were created.

The potential problem we've found is that Algorithm is provided on CryptoOperation and Key as a readonly attribute. This syntactic form is strictly prohibited by WebIDL [5], which states:

"The type of the attribute, after resolving typedefs, MUST NOT be a nullable or non-nullable version of any of the following types: 
.a sequence type
.a dictionary
.a union type that has a nullable or non-nullable sequence type or dictionary as one of its flattened member types" [6]

Instead, the recommend technique for providing a dictionary type as output is via an operation, such as "getAlgorithm()". We'd like to recommend that we make a change now to convert the two occurrences that use Algorithm as an attribute in the spec to use a method instead. This will avoid a late-breaking API change later (at LC or CR) when other working groups review the spec and uncover this violation.  We're open to alternative name suggetions-"getAlgorithm" just seems like the least amount of churn to address the issue.

This suggestion will have the following impact on the Key and CryptoOperation interfaces:

interface CryptoOperation : EventTarget {
  void init();
  void processData(ArrayBufferView buffer);
  void complete();
  void abort();

  readonly attribute Key? key;
  readonly attribute any result;

  Algorithm getAlgorithm();

  [TreatNonCallableasNull] attribute Function? onabort;
  [TreatNonCallableAsNull] attribute Function? onerror;
  [TreatNonCallableAsNull] attribute Function? oninit;
  [TreatNonCallableAsNull] attribute Function? onprogress;
  [TreatNonCallableAsNull] attribute Function? oncomplete;
};
  
interface Key {
  readonly attribute KeyType type;
  readonly attribute bool extractable;
  readonly attribute KeyUsage[] keyUsage;

  Algorithm getAlgorithm();
};
      
Thanks,
IE team


[1] https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html
[2] https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#algorithm-dictionary
[3] https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#cryptooperation-interface
[4] https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#key-interface 
[5] http://dev.w3.org/2006/webapi/WebIDL/
[6] http://dev.w3.org/2006/webapi/WebIDL/#idl-attributes

Received on Thursday, 2 May 2013 20:47:32 UTC