Re: crypto-ISSUE-37: Method naming [Web Cryptography API]

On Tue, Aug 28, 2012 at 6:44 PM, Web Cryptography Working Group Issue
Tracker <> wrote:
> crypto-ISSUE-37: Method naming [Web Cryptography API]
> Raised by: Ryan Sleevi
> On product: Web Cryptography API
> All of the methods on the Crypto interface follow the "createFoo" form, such as createEncrypter or createKeyDeriver.
> When originally specified, the verb was associated with the action that would be performed, such as "encrypt" or "decrypt". As a result of ACTION-14, it was suggested this be renamed to "createEncrypter" et all, to indicate that the Crypto interface method did not itself perform the encryption.
> However, this suffers from the following concern:
> 1) Method names are noticeably longer, by virtue of needing to have a "create" prefix and an "er" suffix
> 2) With the exception of KeyStorage and getRandomValues, all methods available on window.crypto are of the factory form "createFoo"
> 3) There are localization issues regarding Encryptor/Encrypter and Decrypter/Decryptor, both of which are valid spellings and may vary by locality.

Solution 1:
As proposed by Vijay as part of ISSUE-12 [1], have all cryptographic
operations, key derivation, and key agreement be brought under a
single object, "CryptoOperation", with a single method,

Sample code:
var a = window.crypto.createOperation("encrypt", ...);

- Avoids the need to have "er" suffices

- Methods such as "processData()" are not generally applicable to
derivation or key agreement, and may encourage or mislead developers
into treating agreement protocols (that is, multi-leg exchanges) as
single algorithms, which would be conflating a high level and low
level API functionality
- Without the additional context, the "Operation" of createOperation
can be a confusing catch-all of functionality - much like the
previously mentioned "void* DoIt(void* params)" C++ universal API.

Solution 2:
Define a Constructor for the CryptoOperation, and to fully remove the
create* functions from the Crypto interface.

[Constructor(OperationType operation, Algorithm algorithm,
OperationParameters parameters)]
interface CryptoOperation { ... };

Functionally, this is a variant of Vijay's proposal from Solution 1.

Sample Code:
var a = CryptoOperation("encrypt", ...);

- Does not require the "create" prefix or "er/or" suffix

- Same as Vijay's proposal

Solution 3:
Create objects for each of the "primitive" cryptographic operations,
and combine with Solution 2 to define constructors for each object.

[Constructor(AlgorithmIdentifier algorithm, ...)]
interface Encrypter : CryptoOperation { ... };
interface Decrypter : CryptoOperation { ... };
interface KeyDeriver : KeyOperation { ... };

Sample Code:
var a = Encrypter(...);

- Avoids the "create" prefix
- Permits different object hierarchies to be returned, the same under
the current API.

- Still suffers the "er"/"or" suffix and "verb-er" naming.


Received on Wednesday, 29 August 2012 03:24:53 UTC