This document is for extension developers and describes how to use the extension API enterprise.platformKeys for client certificate enrollment. MotivationClient certificates allow secure authentication to digital resources, like networks or web resources. A typical certificate based authentication protocol is Transport Layer Security (TLS, formerly known as SSL) and the protocols that are built on top like EAP-TLS for network authentication and HTTPS for web resources. This article describes how to manage and make use of client certificates on Chrome OS using the enterprise.platformKeys extension API: in particular, how to provision a new client certificate and how to use a client certificate for network or web authentication. OverviewMany certificate enrollment protocols exist, like SCEP, EST or CMC, that define the communication between the client (in this case, the Chrome OS device) and the Certificate Authority (CA), which can be accompanied by a Registration Authority. The enterprise.platformKeys API is designed in a way that extensions have the freedom to implement any enrollment protocol based on what is supported by the target Certificate Authority. Independent of which specific protocol is used to communicate, the following steps describe the typical flow of a certificate enrollment:
After successful enrollment the certificate can be used to authenticate to resources like a network or a web page. The enterprise.platformKeys APIThis extension API of Chrome OS allows extensions to generate a key pair, sign a certification request, and to manage the installed client certificates (import, get and remove certificates). Using this API, an extension can drive the process of installing a new client certificate to a Chrome OS device. In order to use the API, an extension must be pre-installed by user policy. Only extensions installed by policy can use the API. How to implement the enrollment process in an extension1. The enrollment can be started by several events.
2. The extension needs some configuration about the enrollment process, at a minimum the URL of the CA and maybe attributes to embed in the certification request. The configuration can
3. To obtain credentials to authenticate the certification request at the CA, the extension can present any UI and ask the user to provide the credentials or use any other APIs, for example, OAuth. 4. The extension has to obtain the user Token (with the id function getUserToken(callback) { chrome.enterprise.platformKeys.getTokens(function(tokens) { for (var i = 0; i < tokens.length; i++) { if (tokens[i].id == "user") { callback(tokens[i]); return; } } callback(null); }); }
// Equivalent to 65537
5. Extract the public key from the key handle using the subtleCrypto.exportKey method of the Token:
6. Create the content for the certification request in the extension. This request must contain at least the public key. The CA may expect additional attributes that must be added. If the request is PKCS#10 based, for example, the open source library forge may be used.
7. Sign the content of the certification request (using the subtleCrypto.sign method of the Token) and create the final request from the content and the signature. Any subsequent attempt to use the same key for signing will fail for security reasons: This API guarantees that only Chrome OS itself can use the private key and the certificate for authentication.
8. Send the certification request to the CA and receive the client certificate (e.g. using XMLHttpRequest)
9. Install the client certificate using enterprise.platformKeys.importCertificate
chrome.enterprise.platformKeys.importCertificate(userToken.id, certificate); 10. Different methods to use the client certificate for authentication are available For network authentication:
For web pages requiring client certificate authentication:
Note that the enterprise.platformKeys API guarantees, that client certificates imported using the API can only be used by Chrome OS itself for authentication. The extension is not able to drive any authentication with such a certificate and in particular the API guarantees that the certificate can’t be extracted to authenticate any other user or device. Re-enrollmentTo determine whether any valid client certificate is already installed and to check the expiration of the installed certificates, an extension can use the platformKeys.getCertificates function and if necessary trigger the process to obtain a new client certificate.
An installed certificate can be removed from the user’s certificate store using the function enterprise.platformKeys.removeCertificate. As client certificates can be selected automatically (see last step in the enrollment process above), unnecessary certificates should be removed to prevent conflicts. |