keystore_service.mojom 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409
  1. // Copyright 2020 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. module crosapi.mojom;
  5. import "chromeos/crosapi/mojom/keystore_error.mojom";
  6. // This interface mirrors the enterprise.platformKeys extension API.
  7. // TODO(https://crbug.com/1128022): Figure out the appropriate API surface for
  8. // long-term stabilization.
  9. // The system has a keystore and a certificate store. Keys are tuples
  10. // of (private key, public key). These are generated by the system and the
  11. // private key is never shared. Certificates provide proof of ownership of a
  12. // private key. There are many uses for keys and certificates -- this interface
  13. // currently focuses on the use cases for the enterprise_platform_keys extension
  14. // API.
  15. // Unless otherwise noted, all certificates are DER encoded X.509. In addition,
  16. // the certificates allow UTF-8 encoding in fields where PrintableString is
  17. // expected to support enterprises with non-compliant DER-encodings. See
  18. // crbug.com/770323 and crbug.com/788655.
  19. // Both keystores and certificate stores have two variants: device and user.
  20. // Device keys/certificates are available to all affiliated users on the device.
  21. // User keys/certificates are only available to the current user.
  22. [Stable, Extensible]
  23. enum KeystoreType {
  24. kUser = 0,
  25. kDevice = 1,
  26. };
  27. // Input parameters for RSASSA-PKCS1-v1_5. Parameters other than modulus_length
  28. // and sw_backed are currently not supported when used as inputs to
  29. // GenerateKey().
  30. [Stable]
  31. struct KeystorePKCS115Params {
  32. [MinVersion=0]
  33. uint32 modulus_length@0;
  34. [MinVersion=1]
  35. array<uint8>? public_exponent@1;
  36. // If true, generate a software-backed key.
  37. [MinVersion=16]
  38. bool sw_backed@2;
  39. };
  40. // Input parameters for ECDSA. |named_curve| uses WebCrypto nomenclature.
  41. // Currently "P-256" is the only supported curve.
  42. [Stable]
  43. struct KeystoreECDSAParams {
  44. string named_curve;
  45. };
  46. // A signing algorithm is fully described by choice of algorithm and parameters.
  47. [Stable]
  48. union KeystoreSigningAlgorithm {
  49. KeystorePKCS115Params pkcs115;
  50. KeystoreECDSAParams ecdsa;
  51. };
  52. // The name of a WebCrypto signing algorithm.
  53. [Stable, Extensible]
  54. enum KeystoreSigningAlgorithmName {
  55. kUnknown = 0,
  56. kRsassaPkcs115 = 1,
  57. kEcdsa = 2,
  58. };
  59. // Recognized WebCrypto signing schemes.
  60. [Stable, Extensible]
  61. enum KeystoreSigningScheme {
  62. [Default] kUnknown = 0,
  63. kRsassaPkcs1V15None = 1, // The data is PKCS#1 v1.5 padded but not hashed.
  64. kRsassaPkcs1V15Sha1 = 2,
  65. kRsassaPkcs1V15Sha256 = 3,
  66. kRsassaPkcs1V15Sha384 = 4,
  67. kRsassaPkcs1V15Sha512 = 5,
  68. kEcdsaSha1 = 6,
  69. kEcdsaSha256 = 7,
  70. kEcdsaSha384 = 8,
  71. kEcdsaSha512 = 9,
  72. };
  73. // Returned by ChallengeAttestationOnlyKeystore().
  74. [Stable]
  75. union ChallengeAttestationOnlyKeystoreResult {
  76. // Implies failure.
  77. string error_message;
  78. // Implies success.
  79. array<uint8> challenge_response;
  80. };
  81. [Stable]
  82. union KeystoreBinaryResult {
  83. // Implies failure.
  84. KeystoreError error;
  85. // Implies success.
  86. array<uint8> blob;
  87. };
  88. // Returned by GetCertificates().
  89. [Stable]
  90. union GetCertificatesResult {
  91. // Implies failure.
  92. KeystoreError error;
  93. // Implies success.
  94. array<array<uint8>> certificates;
  95. };
  96. // Returned by SelectClientCertificates().
  97. [Stable]
  98. union KeystoreSelectClientCertificatesResult {
  99. // Implies failure.
  100. KeystoreError error;
  101. // A list of DER encoded X.509 certificates. Implies success.
  102. array<array<uint8>> certificates;
  103. };
  104. // Returned by GetKeyStores().
  105. [Stable]
  106. union GetKeyStoresResult {
  107. // Implies failure.
  108. KeystoreError error;
  109. // Implies success.
  110. array<KeystoreType> key_stores;
  111. };
  112. // Returned by GetPublicKey() on success.
  113. [Stable]
  114. struct GetPublicKeySuccessResult {
  115. // The public key of the matching certificate.
  116. array<uint8> public_key;
  117. // Provides details about the signing algorithm.
  118. KeystoreSigningAlgorithm algorithm_properties;
  119. };
  120. // Returned by GetPublicKey().
  121. [Stable]
  122. union GetPublicKeyResult {
  123. // Implies failure.
  124. KeystoreError error;
  125. // Implies success.
  126. GetPublicKeySuccessResult success_result;
  127. };
  128. // The enum of possible tags that can be attached to a key pair. The tag values
  129. // must be powers of 2.
  130. [Stable, Extensible]
  131. enum KeyTag {
  132. kNoTags = 0,
  133. kCorporate = 1,
  134. };
  135. [Stable]
  136. union GetKeyTagsResult {
  137. // Implies failure.
  138. KeystoreError error;
  139. // Implies success. A bitmask of `KeyTag` flags.
  140. uint64 tags;
  141. };
  142. // DEPRECATED, use `KeystoreBinaryResult` instead.
  143. [Stable]
  144. union DEPRECATED_ExtensionKeystoreBinaryResult {
  145. // Implies failure.
  146. string error_message;
  147. // Implies success.
  148. array<uint8> blob;
  149. };
  150. // DEPRECATED, use `GetPublicKeyResult` instead.
  151. // Returned by DEPRECATED_GetPublicKey().
  152. [Stable]
  153. union DEPRECATED_GetPublicKeyResult {
  154. // Implies failure.
  155. string error_message;
  156. // Implies success.
  157. GetPublicKeySuccessResult success_result;
  158. };
  159. // DEPRECATED, use `GetKeyStoresResult` instead.
  160. // Returned by DEPRECATED_GetKeyStores().
  161. [Stable]
  162. union DEPRECATED_GetKeyStoresResult {
  163. // Implies failure.
  164. string error_message;
  165. // Implies success.
  166. array<KeystoreType> key_stores;
  167. };
  168. // DEPRECATED, use `GetCertificatesResult` instead.
  169. // Returned by DEPRECATED_GetCertificates().
  170. [Stable]
  171. union DEPRECATED_GetCertificatesResult {
  172. // Implies failure.
  173. string error_message;
  174. // Implies success.
  175. array<array<uint8>> certificates;
  176. };
  177. // DEPRECATED, use `KeystoreBinaryResult` instead.
  178. // Returned by methods that either return a string, or an error.
  179. [Stable, RenamedFrom="crosapi.mojom.KeystoreStringResult"]
  180. union DEPRECATED_KeystoreStringResult {
  181. // Implies failure.
  182. string error_message;
  183. // Implies success.
  184. string challenge_response;
  185. };
  186. // This interface is implemented by ash-chrome. It provides lacros-chrome a
  187. // mechanism to modify and query the attestation-only and generate purpose
  188. // keystores.
  189. [Stable, Uuid="308635fd-110b-4f24-bfa8-9f43be31c61e"]
  190. interface KeystoreService {
  191. // This API serves a challenge to a special "attestation-only" keystore. This
  192. // keystore only contains 2 private keys (1 for the user, 1 for the device).
  193. // The challenge must be generated via the Verified Access Web API. If
  194. // |migrate| is true, then after the attestation, the key is migrated
  195. // from the attestation-only keystore to the regular keystore. A new
  196. // "attestation-only" key is generated on demand if a key does not exist
  197. // because it was recently migrated. If a key is migrated, the expectation is
  198. // that the caller will later call ImportCertificate() to associate a
  199. // certificate with the migrated key.
  200. [MinVersion=15]
  201. ChallengeAttestationOnlyKeystore@20(
  202. KeystoreType type, array<uint8> challenge, bool migrate) =>
  203. (ChallengeAttestationOnlyKeystoreResult result);
  204. // Returns the keystores available to the client. These are used as inputs to
  205. // the other methods on this interface.
  206. [MinVersion=12]
  207. GetKeyStores@16() => (GetKeyStoresResult result);
  208. // Returns the list of all certificates that were issued by one of the
  209. // |certificate_authorities|. |certificate_authorities| is a list of
  210. // DER-encoded X.509 DistinguishedName of certificate authorities. If
  211. // |certificate_authorities| is empty, all certificates will be returned.
  212. [MinVersion=9]
  213. SelectClientCertificates@11(array<array<uint8>> certificate_authorities)
  214. => (KeystoreSelectClientCertificatesResult result);
  215. // Returns the certificates in the indicated keystore. The result is an array
  216. // of DER encoded X.509 certificates.
  217. [MinVersion=13]
  218. GetCertificates@17(KeystoreType keystore) =>
  219. (GetCertificatesResult result);
  220. // Adds a DER encoded X.509 certificate to the indicated keystore. Returns
  221. // empty string on success. It is only valid to call this with a certificate
  222. // whose corresponding private key is already present in the key store. This
  223. // must have been previously generated via GenerateKey().
  224. // TODO(crbug.com/657632): combine |is_error| and |error| into an optional
  225. // |error| when mojo supports optional enums.
  226. [MinVersion=14]
  227. AddCertificate@18(KeystoreType keystore, array<uint8> certificate) =>
  228. (bool is_error, KeystoreError error);
  229. // Removes a DER encoded X.509 certificate from the indicated keystore.
  230. // Returns empty string on success.
  231. // TODO(crbug.com/657632): combine |is_error| and |error| into an optional
  232. // |error| when mojo supports optional enums.
  233. [MinVersion=14]
  234. RemoveCertificate@19(KeystoreType keystore, array<uint8> certificate) =>
  235. (bool is_error, KeystoreError error);
  236. // Checks whether |certificate| certifies a key that allows usage of the
  237. // WebCrypto algorithm |algorithm_name|. If so, returns the key info and
  238. // details about the signing algorithm. |certificate| must be a DER encoded
  239. // X.509 certificate.
  240. [MinVersion=11]
  241. GetPublicKey@15(array<uint8> certificate,
  242. KeystoreSigningAlgorithmName algorithm_name) =>
  243. (GetPublicKeyResult result);
  244. // Generates a private/public key-pair with |algorithm| and stores the results
  245. // in |keystore|. Returns the public key as a binary blob.
  246. [MinVersion=6]
  247. GenerateKey@8(KeystoreType keystore,
  248. KeystoreSigningAlgorithm algorithm) =>
  249. (KeystoreBinaryResult result);
  250. // Removes the key pair if no matching certificates exist. Only keys in the
  251. // given |keystore| are considered. |is_error| indicates if the operation
  252. // succeeded. If |is_error| is true, then |error| contains the error code.
  253. // TODO(crbug.com/657632): combine |is_error| and |error| into an optional
  254. // |error| when mojo supports optional enums.
  255. [MinVersion=8]
  256. RemoveKey@10(KeystoreType keystore,
  257. array<uint8> public_key) =>
  258. (bool is_error, KeystoreError error);
  259. // Signs some data using a previously generated key, indicated with
  260. // |public_key|. |scheme| is the WebCrypto signing scheme. If
  261. // |is_keystore_provided| is true, |keystore| holds a valid value. Otherwise
  262. // the key will be searched in all available key stores.
  263. // TODO(crbug.com/657632): combine |is_keystore_provided| and |keystore| into
  264. // an optional |keystore| when mojo supports optional enums.
  265. [MinVersion=7]
  266. Sign@9(bool is_keystore_provided, KeystoreType keystore,
  267. array<uint8> public_key, KeystoreSigningScheme scheme,
  268. array<uint8> data) =>
  269. (KeystoreBinaryResult result);
  270. // Returns key tags assigned to the key pair of the |public_key|.
  271. [MinVersion=10]
  272. GetKeyTags@12(array<uint8> public_key) => (GetKeyTagsResult result);
  273. // Adds new tags to the key pair of the |public_key|.
  274. [MinVersion=10]
  275. AddKeyTags@13(array<uint8> public_key, uint64 tags) =>
  276. (bool is_error, KeystoreError error);
  277. // Returns true if the current ChromeOS user can grant unlimited sign
  278. // permission for |public_key| to extensions.
  279. [MinVersion=10]
  280. CanUserGrantPermissionForKey@14(array<uint8> public_key) =>
  281. (bool is_allowed);
  282. // DEPRECATED, use `GenerateKey` instead.
  283. // Generates a private/public key-pair with |algorithm| and stores the results
  284. // in |keystore|. Returns the public key as a binary blob. Also generates
  285. // additional metadata to make the key available for future ExtensionSign
  286. // calls.
  287. [MinVersion=2]
  288. DEPRECATED_ExtensionGenerateKey@3(KeystoreType keystore,
  289. KeystoreSigningAlgorithm algorithm,
  290. [MinVersion=5]
  291. string? extension_id) =>
  292. (DEPRECATED_ExtensionKeystoreBinaryResult result);
  293. // DEPRECATED, use `Sign` instead.
  294. // Signs some data using a previously generated key, indicated with
  295. // |public_key|. |scheme| is the WebCrypto signing scheme. |extension_id| is
  296. // needed to determine if the extension is allowed to use the key.
  297. [MinVersion=4]
  298. DEPRECATED_ExtensionSign@7(KeystoreType keystore, array<uint8> public_key,
  299. KeystoreSigningScheme scheme,
  300. array<uint8> data, string extension_id) =>
  301. (DEPRECATED_ExtensionKeystoreBinaryResult result);
  302. // DEPRECATED, use `GetPublicKey` instead.
  303. // Checks whether |certificate| certifies a key that allows usage of the
  304. // WebCrypto algorithm |algorithm_name|. If so, returns the key info and
  305. // details about the signing algorithm. |certificate| must be a DER encoded
  306. // X.509 certificate.
  307. DEPRECATED_GetPublicKey@6(array<uint8> certificate,
  308. KeystoreSigningAlgorithmName algorithm_name) =>
  309. (DEPRECATED_GetPublicKeyResult result);
  310. // DEPRECATED, use `GetKeyStores` instead.
  311. // Returns the keystores available to the client. These are used as inputs to
  312. // the other methods on this interface.
  313. [MinVersion=1]
  314. DEPRECATED_GetKeyStores@1() => (DEPRECATED_GetKeyStoresResult result);
  315. // DEPRECATED, use `GetCertificates` instead.
  316. // Returns the certificates in the indicated keystore. The result is an array
  317. // of DER encoded X.509 certificates.
  318. [MinVersion=2]
  319. DEPRECATED_GetCertificates@2(KeystoreType keystore) =>
  320. (DEPRECATED_GetCertificatesResult result);
  321. // DEPRECATED, use `AddCertificate` instead.
  322. // Adds a DER encoded X.509 certificate to the indicated keystore. Returns
  323. // empty string on success. It is only valid to call this with a certificate
  324. // whose corresponding private key is already present in the key store. This
  325. // must have been previously generated via GenerateKey().
  326. [MinVersion=2]
  327. DEPRECATED_AddCertificate@4(KeystoreType keystore,
  328. array<uint8> certificate) =>
  329. (string error);
  330. // DEPRECATED, use `RemoveCertificate` instead.
  331. // Removes a DER encoded X.509 certificate from the indicated keystore.
  332. // Returns empty string on success.
  333. [MinVersion=2]
  334. DEPRECATED_RemoveCertificate@5(KeystoreType keystore,
  335. array<uint8> certificate) =>
  336. (string error);
  337. // DEPRECATED, use `ChallengeAttestationOnlyKeystore` instead.
  338. // This API serves a challenge to a special "attestation-only" keystore. This
  339. // keystore only contains 2 private keys (1 for the user, 1 for the device).
  340. // The challenge must be generated via the Verified Access Web API. If
  341. // |migrate| is true, then after the attestation, the key is migrated
  342. // from the attestation-only keystore to the regular keystore. A new
  343. // "attestation-only" key is generated on demand if a key does not exist
  344. // because it was recently migrated. If a key is migrated, the expectation is
  345. // that the caller will later call ImportCertificate() to associate a
  346. // certificate with the migrated key.
  347. DEPRECATED_ChallengeAttestationOnlyKeystore@0(
  348. string challenge, KeystoreType type, bool migrate) =>
  349. (DEPRECATED_KeystoreStringResult result);
  350. };