Technology Nexus Web Cryptography API use-cases

Hi,
I have create a text describing our (Technology Nexus) use-cases. It is a combination of something we do today and what we hope to be able to do with this new API. The text is Wiki formated.

= Technology Nexus Web Cryptography API use-cases =
== Background ==
Technology Nexus is a software company that develops PKI software. In the Nexus product suite there are products for the whole life cycle of certificates, everything from issuing to doing the signing/authentication to validation and revocation. These are products that all has been central to the successful swedish PKI deployment with over 80% of the swedish population using products developed by Technology Nexus.
For the Web Cryptography API a product called Nexus Personal is the most relevant one even though the other ones certainly will be affected by this development. Nexus Personal is a crypto provider that implements the common PKCS#11 interface and the Microsoft CryptoAPI. By doing this Nexus Personal provides smart card access to these interfaces. Further it is well integrated with the browser by plugins for doing application level signatures/authentication from webpages, this is where the new Web Cryptography API would fit perfectly.

== Usecases ==
These are the usecases most central to our current business. As mentioned in the background section there is a focus on signatures.
=== Authenticate with certificate ===
This usecase is quite common for bank customers in Sweden that uses the Swedish BankID for authentication to their internet bank.
* The users enters a web-app (e.g. bank) and selects to authenticate
* The server returns a challenge with a filter to limit selectable certificate to those relevant to this server.
* A javascript picks up this challenge and the filter and asks Web Cryptography API for a signature of the challenge with a certificate that fulfills filter requirement.
'''NOTE''': Here it is important for the javascript to be able to point to a specific crypto provider or a crypto provider with support for certain operations/algorithms. the rational for this is that in sweden we have two major E-ID providers and they do not like signatures from each others clients, i.e. they want to be certain that the signature is done by a certain client. Further this is a usability issue if end user has to select Crypto Provider.

'''NOTE''': Currently we can filter on a combination of:
** Issuer DN (regexp) (can be a way of indicating only certificate on smart card)
** Subject DN (regexp)
** Certificate policy (list of object identifiers)
** Most recently used (i.e. sign with certificate corresponding to most recently used authentication certificat - not relevant for authentication, but for signing
** key usage (normally implied by operation)
* As Nexus Personal is registered as a PKCS#11 provider/CryptoAPI the authentication request gets directed to it.
'''NOTE''': The interaction with Nexus Personal for doing this is today done with a plugin.
* Nexus Personal pops up a dialog for selecting authentication certificate
* If a smart card is attached user can select to authenticate with certificates on it too (if they match filter criteria),
'''NOTE''': Only certificates for authentication is selectable since it was a authentication that was requested (key usage)
* After a certificate is selected by the user Nexus Personal asks the user to enter PIN or if the card reader has a PIN pad the user is asked to use it.
* Nexus personal interacts with the card and create a signature on the challenge
* The signature is returned to the javascript that submits it to the server which validate that the signature is valid for this application.

=== Sign form data ===
In swedish government services and bank services Authentication is seldom enough, before every major transaction of some sort the transaction primitives has to be signed.
* User browses a web-app doing some operations, e.g. filling out tax-declarations, shopping, doing some bank transactions.
* User eventualy clicks finish, but before the operation is executed it has to be signed.
* A javascript creates a string representation TBS (To Be Signed) of the operations to be carried out
'''NOTE''': Most commonly an aggregation of a web form possible compiled together with a template.
* The TBS is passed to the Web Cryptography API with desired signing method and crypto provider reference
* Since Nexus Personal is registered as the crypto provider the signing request gets directed to it
* Nexus personal shows the user the TBS as it is the actual thing that will be signed
'''NOTE''': The TBS contains two parts visible and non-visible the visible part is shown to the user it is formatted to be in good human readable format. Then there is the non-visible part which contains the same information but in a machine readable format. If the transaction is contested it has to be shown in court that the non-visible content corresponds to what the user actually saw.
* User selects among certificates on smart card and certificates managed by Nexus Personal, then the user selects to sign.
* User is asked for PIN either through standard in or PIN-pad on card reader, depending on where key is stored.
* Nexus Personal creates a signature for the TBS.
'''NOTE''': Currently the signature is a PKCS7 or XMLDSIG
* The signature is passed back to the javascript that submits the signature and the TBS.
* Server validates signature and performs form action if signature TBS and form data is aligned with each other

=== Sign file ===
In many cases the user has to consent to agreements of some sort when performing online actions e.g. opening a bank account. And in some cases the user uploads a file that should be signed before it is commited.
==== Signing linked file ====
* User browses a web-app and performs an action needing a digital signature, e.g. open a new bank account.
* In opening this account there is an agreement that has to be signed
* The page contains a link to the agreement pdf
* Javascript creates a TBS, the TBS contains the link to the agreement
* The TBS is passed to the Web Cryptography API with desired signing method
* Since Nexus personal is registered as the crypto provider the signing request is gets directed to it
* Nexus Personal shows the TBS with the link to the file,
* Nexus Personal gives the user the possibility to look at the linked file and creates a hash that is included in the TBS.
* Use looks at the TBS and the file and when satisfied the user selects a signing certificate to do the signing with, the certificate might be managed by Nexus Personal or an attached smart card
* User is prompted to enter PIN either on PIN-pad or standard in
* Nexus Personal creates the signature and passes it back to the javascript
* The javascript sends signature TBS and form data to the server for validation.
* Server validates that all parts of the signature is valid and so on before performing desired action.

==== Signing uploaded files ====
* User browses a web-app and performs an action needing a digital signature, e.g. submitting a homework
* In doing this the teacher wants to know that the submitted homework actually comes from this student, therefor it has to be signed.
* User fills out a form regarding the task and then selects the file containing the homework
* Javascript packages a TBS with the form data and a reference to the file
'''NOTE''': The file reference might be possible to get with the HTML5 FileReader API
* The package is passed to the Web Cryptography API with desired signing method
* Since Nexus personal is registered as the crypto provider the signing request is gets directed to it
* Nexus Personal shows the TBS and the file that will be signed
* Nexus Personal gives the user the possibility to look at the file
* Use looks at the TBS and the file and when satisfied the user selects a signing certificate to do the signing with, the certificate might be managed by Nexus Personal or an attached smart card
* User is prompted to enter PIN either on PIN-pad or standard in
* Nexus Personal creates the signature and passes it back to the javascript
* The javascript sends signature TBS and form data to the server for validation.
* Server validates that all parts of the signature is valid and so on before performing requested action.

=== Store symmetric key in a protected area ===
Technology Nexus also creates a web-based OATH token, this token is currently ran from a native wrapper application. With a secure key store accessible directly from javascript it would be possible to make this client much more lightweight and still achieve desired security. To do this some aspects has to be fulfilled by the Web Cryptography API:
* Keys MUST NOT be possible to extract from key store with javascript, to prevent token theft.
* With a reference to the key it is possible to create a HMAC of a challenge, to generate the one time password.
* Key are protected by same origin policy, to avoid other sites to generate OTPs
* Secure random numbers, to enable secure provisioning (DSKPP)

=== Certificate enrollment ===
A large part of Technology Nexus business is issuing of certificates.
==== Self service ====
This could be for issuing of temporary certificates, in case of misplacement.
* A user has authenticated to a self-service web-portal.
* The users selects to create a certificate.
* User enters reason for issuing and other details required for issuing.
* A javascript asks the Web Cryptography API to create a CSR (or a JSON equivalent)
* Since Nexus Personal is registered as the crypto provider the CSR request gets directed to it
* Nexus Personal generates keys, asks user for PIN and creates a CSR
'''NOTE''': This operation might be passed to a smart card if user selects to use a smart card as media for the key
* The created CSR is returned to the javascript which submits it to the server.
* The server accept the CSR if user is authenticated with appropriate strength.
* Javascript gets certificate back and passers it back to Nexus Personal through the Web Cryptography API

==== Certificat Authority Administrator ====
* An administrator authenticates to the certificate manager web interface, preferable with a smart card ;)
* The administrator enters details for the certificate that he whites to issue
* A javascript asks the Web Cryptography API to create a CSR (or a JSON equivalent)
* Since Nexus Personal is registered as the crypto provider the CSR request is gets directed to it
* Nexus Personal creates CSR and asks for PIN generates keys and so on
NOTE: This operation might be passed to a smart card if user selects to use a smart card as media for the key
* The created CSR is returned to the javascript which submits it to the server.
* The server accept the CSR if user is authenticated with appropriate strength.
* Javascript gets certificate back and passers it back to Nexus Personal through the Web Cryptography API

=== PIN recovery ===
In are organizations it is often required that the user can do some operation of recovery by him self, to lessen the burden of support.
* A user has forgotten his PIN
* He accesses the self-service-portal where he authenticates with some recovery credentials
* In the portal he selects which certificate to recover (server keeps track of his certificates)
* A JavaScript can can now get the PUK from the server
* The script packages this into a PIN recovery request
'''NOTE''': As for previous usecases it is important to be able to specify crypto provider that manages the certificate.
* The request is received by Nexus Personal
* Nexus personal prompts user to enter a new pin and card is recovered

== Additional notes ==
* It is often important for web-apps to be able to filter/search on certificates but it is also important to not give free access to the certificate since it can cantain sensitive information e.g. social security number.
* When doing signatures both attached and detached signatures are desired.


Samuel Erdtman  |  Developer
Nexus Group  |  www.nexussafe.com<http://www.nexussafe.com/>