[encrypted-media] Reduce ambiguity around the use of "usable"

ddorwin has just created a new issue for 
https://github.com/w3c/encrypted-media:

== Reduce ambiguity around the use of "usable" ==
The word "[un]usable" appears 22 times in the current spec with at 
least three similar but different meanings. We should reduce ambiguity
 and be explicit about the meaning intended in each case. This may 
involve using different words and linking to definitions.

The root of problem is that a key may be _usable_ for decrypting 
content (2) without being in the `"usable"` status (3). Specifically, 
a key with the `"output-restricted"` or `"output-downscaled"` status 
may be _usable_.

In addition to being ambiguous, the multiple uses of "usable" could 
lead to confusion and mistakes by authors who equate the `"usable"` 
status (3) with _usable_ (2). (This issue was brought to my attention 
by someone who encountered such code.)

## Uses

1. Colloquial (usable to do something):
  * "Key sessions and the keys they contain are no longer usable by 
the CDM for decryption..."
  * "... the license and key(s) it contains are no longer usable by 
the client."
  * "...the key(s) in the session will no longer be usable to decrypt 
media data..."
  * "The key is no longer usable to decrypt media data because its 
expiration time has passed."
  * "The key is not currently usable to decrypt media data because of 
an error in the CDM..."
  * "If cdm is no longer usable for any reason..."
1. A specific definition within the Key definition: "A key is 
considered _usable_ if the CDM is certain the key is currently usable 
to decrypt media data"
  * This really seems like a definition in the style of HTML5. It 
should probably be marked up and referenced as such rather than just 
emphasized (`<em>`).
1. The `"usable"` `MediaKeyStatus` value
1. In the Encrypted Block Encountered algorithm


## The Encrypted Block Encountered algorithm
This algorithm (4) uses the term "usable" (no emphasis) in an 
ambiguous way:
>If any of the _available keys_ corresponds to the _block key ID_ and 
is usable, ...

Clearly, we want to use a key if it is currently allowed to decrypt 
the current block, but this is a complex condition that includes:
* `"usable"`
* `"output-restricted"` depending on the stream and possibly other 
conditions
* `"output-downscaled"` (assuming the contents of the block can be 
downscaled)

The NOTE associated with the step above does emphasize "usable":
>If multiple sessions contain a _usable_ key for the _block key ID_, 
...

There is another NOTE at the end of the algorithm that does not:
>These steps are reached when there is no usable key for the block.

The step and NOTEs should be consistent.


## Proposed Actions

1. Create a real definition at (2) and reference it where appropriate.
  * To differentiate the defined term from the colloquial usage and 
`"usable"` `MediaKeyStatus` value, I propose something like **usable 
to decrypt a block**.
1. Provide more clarity near the "definition" (2). This might involve 
expanding the existing NOTE.
1. Ensure the steps and NOTEs in the Encrypted Block Encountered 
algorithm are consistent.
1. Consider updating the `handlekeyStatusesChange()`  example to use 
other statuses and address any possible issues in the comments.

We could also consider renaming `"usable"` `MediaKeyStatus` value, 
However, that would affect existing applications and implementations, 
so changing the prose is probably better.

Please view or discuss this issue at 
https://github.com/w3c/encrypted-media/issues/142 using your GitHub 
account

Received on Friday, 18 December 2015 23:13:11 UTC