KeyGen2 is a web-based protocol for enrolling and managing credentials like X.509 certificates [RFC5280]. The protocol is a part of a security architecture which at the core consists of SKS (Secure Key Store) [SKS]. The KeyGen2 protocol is expressed as a set of JSON [RFC8259] objects. This document contains a description of these objects and how they interact, while the integration with the SKS API is dealt with in the SKS architecture document [SKS].Parts of the protocol rely on cryptographic constructs using JSON which initially were created for the KeyGen2 project, but later became an activity of its own: JSON Signature Format [JSF].Finding the proper balance in a complex scheme like KeyGen2 is a combination of "gut feeling", political considerations, available technology, foresight and market research. If this particular specification hit the right level only time can tell.

"Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away"

Antoine de Saint-Exupéry

Unlike certificate management protocols like CMP [RFC4210], KeyGen2 mandates a two-layer client architecture where the outermost part is talking to the outside world (user and issuer), while an inner part does the communication with the SKS. That is, the client implementation acts as "proxy" enabling the use of a cleartext, JSON based, fairly high-level protocol with issuer, in spite of the fact that SKS only deals with low-level binary data.Another core proxy task is minimizing network roundtrips through SKS command aggregation.Although KeyGen2 depends on a proxy for doing the "Heavy Lifting", E2ES (End To End Security) is achieved through the use of a dynamically created shared secret, which is only known by the SKS and the issuer. For a detailed description of the proxy scheme and the E2ES solution, consult the SKS architecture document [SKS].

This chapter contains a high-level description of the KeyGen2 protocol while the subsequent chapters cover the actual format. To facilitate a straightforward implementation as well as robust operation, KeyGen2 builds on a concept where each major process step is handled by a specific request/response pair as outlined below:

Invocation	Protocol invocation. During this step the user should be alerted by a browser defined dialog telling what is supposed to happen giving as well as providing an option aborting the process. In addition, the issuer may perform a client platform capability query.
ProvisioningInitialization	Creation of a shared session key securing the rest of the interactions between the issuer and the SKS. To support future updates of provisioned credentials, the issuer may also provide a keyManagementKey.
CredentialDiscovery	Optional: Issuer lookup of already provisioned SKS credentials. This is primarily used when keys need to be updated or unlocked.
KeyCreation	Creation of asymmetric key pairs in the SKS. If user-defined PINs are to be set, this is carried out during KeyCreationRequest. After key pairs have been created the public keys are sent to the issuer for certification.
ProvisioningFinalization	Deployment of credentials and associated attributes as well as key management operations are performed in this step. Finally the session is terminated. If the operation is successful, a cryptographic proof is returned to the issuer.

The result of the ProvisioningFinalizationResponse is anticipated to be a custom Termination Message, typically telling the user that the operation succeeded.

Since the interface between the Web and native applications is not (yet) standardized, the invocation of KeyGen2 relies on browser and platform specific solutions. For Android, "Intents" are currently utilized for handing over an invocation URL (including possible session cookies), to a local KeyGen2 "App".

KeyGen2 objects transferred through HTTP must use the Content-Type application/json.Since KeyGen2 is to be regarded as an intrinsic part of the browser, HTTP cookies must be handled as for other HTTP requests.

Errors occurring on the client's side must terminate the session and display an error dialog telling the user what happened.Server-side errors must abort the current server operation and return an appropriate Termination Message to the user. If the KeyGen2 proxy at this stage is rather expecting a KeyGen2 protocol object (see HTTP Dependencies), the client session must be terminated.Whenever a KeyGen2 client session is aborted, the proxy should also abort the associated, potentially active SKS provisioning session (see abortProvisioningSession).

KeyGen2 provides built-in support for the SKS key management operations postUnlockKey, postDeleteKey, postUpdateKey and postCloneKeyProtection.In the case the exact key is not known in advance, you must include a key discovery sequence as described in [SKS] Appendix D, Remote Key Lookup.

When a KeyGen2 protocol sequence terminates (like when the proxy has sent a ProvisioningFinalizationResponse object to the server), the browser must return to its "normal" state, ready for receiving a matching HTTP body containing a HTML page or similar.Note that returned data must target the same window object which was used during invocation.

JSON objects are described as tables with associated properties. When a property holds a JSON object this is denoted by a link to the actual definition. Properties may either be mandatory (M) or optional (O) as defined in the "Req" column.Array properties are identified by [ ] x-y where the range expression represents the valid number of array elements. In some JSON objects there is a choice from a set of mutually exclusive alternatives.
This is manifested in object tables like the following:

Property selection 1	Type selection 1	Req	Comment selection 1
Property selection 2	Type selection 2		Comment selection 2

The table below shows how the data types used by this specification are mapped into native JSON types:

Note that "Type" refers to the element type for arrays.

The following tables describe the KeyGen2 JSON structures in detail.Entries written in italics like generatedKey represent sub objects, while the other entries such as InvocationRequest consitute of the actual messages.

EC curves can be expressed in SKS [SKS] or JWA [RFC7518] notation.The following table shows the mandatory to support curve names:

SKS Name	JWA Name
https://webpki.github.io/sks/algorithm#ec.nist.p256	P-256
https://webpki.github.io/sks/algorithm#ec.nist.p384	P-384
https://webpki.github.io/sks/algorithm#ec.nist.p521	P-521
https://webpki.github.io/sks/algorithm#ec.secg.p256k1	-
https://webpki.github.io/sks/algorithm#ec.brainpool.p256r1	-

In the following KeyGen2 sample run the issuer requests that the client (SKS) creates an RSA 2048-bit key protected by a user-set PIN governed by a number of issuer-defined policies.Finally, the issuer provides a certificate and a platform-adapted logotype.For information regarding the cryptographic constructs, consult the SKS architecture manual.

InvocationRequest
{   "@context": "https://webpki.github.io/keygen2#20190318",   "@qualifier": "InvocationRequest",   "serverSessionId": "142f1bdb286XVQnqmIRc1bSzm-QN-ZJk",   "action": "manage",   "clientCapabilityQuery": ["https://webpki.github.io/keygen2/logotype#list"] }
After a compatible browser has received this message, a dialog like the following is shown to user: Credential Enrollment The following provider wants to create a login credential for you: issuer.example.com Cancel   OK   If the user accepts the request, the following response is sent back to the server:
InvocationResponse
{   "@context": "https://webpki.github.io/keygen2#20190318",   "@qualifier": "InvocationResponse",   "serverSessionId": "142f1bdb286XVQnqmIRc1bSzm-QN-ZJk",   "clientCapabilities": [{     "type": "https://webpki.github.io/keygen2/logotype#list",     "imageAttributes": {       "mimeType": "image/png",       "width": 94,       "height": 74     }   }] }
When the server has received the response above, it creates an ephemeral EC key pair and returns the public part to the client together with other session parameters:
ProvisioningInitializationRequest
{   "@context": "https://webpki.github.io/keygen2#20190318",   "@qualifier": "ProvisioningInitializationRequest",   "serverSessionId": "142f1bdb286XVQnqmIRc1bSzm-QN-ZJk",   "serverTime": "2019-04-08T16:33:30Z",   "sessionKeyAlgorithm": "https://webpki.github.io/sks/algorithm#session.1",   "sessionKeyLimit": 20,   "sessionLifeTime": 300,   "serverEphemeralKey": {     "kty": "EC",     "crv": "P-256",     "x": "cpxUxJVt-is8bgWRFm6RuvUkxyv7xJ7PbeT1BCQNNws",     "y": "De7jXYsdL46ikHOWeC-V-AcNM/RURpu6ZgcVAxLUwns"   } }
Next the client generates a matching ephemeral EC key pair and sends the public part back to the server including a client session-ID, key attestation, device-certificate, etc.:
ProvisioningInitializationResponse
{   "@context": "https://webpki.github.io/keygen2#20190318",   "@qualifier": "ProvisioningInitializationResponse",   "serverSessionId": "142f1bdb286XVQnqmIRc1bSzm-QN-ZJk",   "clientSessionId": "39NMWamKtHumJFfdIGkDrLP-NMB-5Lwo",   "serverTime": "2019-04-08T16:33:30Z",   "clientTime": "2019-04-08T18:33:36+02:00",   "clientEphemeralKey": {     "kty": "EC",     "crv": "P-256",     "x": "tQXczn7qxGgcLpOVBuw5i-tMHxbJTUF6k3RZGsjdauc",     "y": "jIlm8sXwknZeQQDTxkfwXKUdhubt6JcqQYA6S8Dm3AE"   },   "deviceId": {     "certificatePath": ["MIIC2DCCAcCgAwIBAgIGARTWcc7VMCSq....awCV4OfAGXLIwJBCp85AN7KNdcJfL"]   },   "attestation": "KMUpOesC8nDTLpu8PppsSGg1j....WiwvUcVpbNudbY14lLks8RQuwoiU" }
After these message exchanges, the SKS and server (issuer) have established a shared session-key, which is used for securing the rest of the session through MAC and encryption operations.   SKS API Reference: createProvisioningSession.   In the sample a request for creating a key is subsequently returned to the client:
KeyCreationRequest
{   "@context": "https://webpki.github.io/keygen2#20190318",   "@qualifier": "KeyCreationRequest",   "serverSessionId": "142f1bdb286XVQnqmIRc1bSzm-QN-ZJk",   "clientSessionId": "39NMWamKtHumJFfdIGkDrLP-NMB-5Lwo",   "keyEntryAlgorithm": "https://webpki.github.io/sks/algorithm#key.1",   "pinPolicySpecifiers": [{     "id": "PIN.1",     "minLength": 4,     "maxLength": 8,     "retryLimit": 3,     "format": "numeric",     "patternRestrictions": ["three-in-a-row", "sequence"],     "mac": "2aUMRubbEk8Xs62QXlPiFJbYlJ68Sw4Fhu48j4uGKXk",     "keyEntrySpecifiers": [{       "id": "Key.1",       "appUsage": "authentication",       "keyAlgorithm": "https://webpki.github.io/sks/algorithm#rsa2048",       "mac": "BQpWMwSz4EsYgliHH6RY3UNWuLsR3eJVapY0CYOUTtI"     }]   }] }
After the browser has received this message, a dialog like the following is shown to user: PIN Code Assignment Set and memorize a PIN for the login credential: • • • • • • Repeat PIN: • • • • • • Cancel   OK   When the user has set a PIN matching the issuer's policy and hit "OK", the requested key pair is created and the public part of the key pair is sent to the server for certification as shown in the response below.   SKS API References: createPinPolicy, createKeyEntry.
KeyCreationResponse
{   "@context": "https://webpki.github.io/keygen2#20190318",   "@qualifier": "KeyCreationResponse",   "serverSessionId": "142f1bdb286XVQnqmIRc1bSzm-QN-ZJk",   "clientSessionId": "39NMWamKtHumJFfdIGkDrLP-NMB-5Lwo",   "generatedKeys": [{     "id": "Key.1",     "publicKey": {       "kty": "RSA",       "n": "uSW5wpfano32Q6oU3xMkFig0r145DN....jkjy1ENPdBQaafvJnuh4x58WPTsVCvjimw",       "e": "AQAB"     },     "attestation": "gyRmTPdW4UdGdXlLkHf40PPRL9xac31eJnyyBtf7-Io"   }] }
The server responds by issuing a matching certificate including an associated logotype.   SKS API References: setCertificatePath, addExtension.
ProvisioningFinalizationRequest
{   "@context": "https://webpki.github.io/keygen2#20190318",   "@qualifier": "ProvisioningFinalizationRequest",   "serverSessionId": "142f1bdb286XVQnqmIRc1bSzm-QN-ZJk",   "clientSessionId": "39NMWamKtHumJFfdIGkDrLP-NMB-5Lwo",   "issuedCredentials": [{     "id": "Key.1",     "certificatePath": ["MIICmDCCAYCgAwIBAgIGAULxF0G....UimDl7Dt7733M0TT8qSpXeYvV0NLX5kM"],     "mac": "FkwauPbrrfJZxuEsMkwOFWIIutzdYbEt3P9kr0CG4dc",     "logotypes": [{       "type": "https://webpki.github.io/keygen2/logotype#list",       "mimeType": "image/png",       "extensionData": "RBgoJkiaJk_IsZAEZUBsZAEZFg....NVBAMTC0RlbW8gU3ViIENBMBTEzMM1oDTM4",       "mac": "uQ5IuLRDpbSkpfU9FHe1grrQ_FXUBfsxsk6HqspjuCU"     }]   }],   "nonce": "_U9YmqyULox2Q53F4l9pQaxjbzlOu2wMo6_FgGAmooQ",   "mac": "_e0T_svX9vXQTuyIxDUmmteM2IwvXbSOEREuqbe7fS4" }
The finalization message which will only be sent to the server if the previous steps were successful.   SKS API Reference: closeProvisioningSession.
ProvisioningFinalizationResponse
{   "@context": "https://webpki.github.io/keygen2#20190318",   "@qualifier": "ProvisioningFinalizationResponse",   "serverSessionId": "142f1bdb286XVQnqmIRc1bSzm-QN-ZJk",   "clientSessionId": "39NMWamKtHumJFfdIGkDrLP-NMB-5Lwo",   "attestation": "Oy8QaNN0orkE2gxlCWrMYHxDNr6m5FTdVpqTqF9eXlI" }
Here the user is supposed to receive an issuer-specific web-page telling what to do next. See Termination Message.

The design of the KeyGen2 protocol was "inspired" by several predecessors, most notably IETF's DSKPP [RFC6063].Funding has been provided by PrimeKey Solutions AB and the Swedish Innovation Board (VINNOVA).

KeyGen2 was primarily developed by Anders Rundgren (anders.rundgren.net@gmail.com) as a part of the OpenKeyStore project [OPENKEY].