1/* 2 * Copyright 2020 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/app/KeyStore.h hrev45434 10 * src/kits/app/KeyStore.cpp hrev45434 11 */ 12 13 14 /*! 15 \file KeyStore.h 16 \ingroup app 17 \ingroup libbe 18 \brief Provides BKeyStore class. 19 20 See the \link app_keystore overview to the Password and Key Storage API 21 \endlink for an introduction to the API. 22*/ 23 24 25/*! 26 \class BKeyStore 27 \ingroup app 28 \ingroup libbe 29 \brief The BKeyStore lets you query, retrieve and store keys in the 30 system's key store. 31 32 Instances of this object give you an easy API to interact with the system's 33 \c keystore_server. This is the central service that manages storing and 34 retrieving keys, as well as managing the authorizations that a user grants 35 to individual applications. 36 37 It is important to note that all calls on this object operate 38 \b synchronously. This means that it should not be used during the event 39 loop of a visible \ref BWindow, as this may cause drawing and interaction 40 issues. 41 42 All operations are performed in the context of a keyring. All systems have 43 at least the \b Master \b keyring. Many of the methods take the name of the 44 keyring as its first argument. Most of the methods in this class have an 45 overloaded variant that operate on the Master keyring. If you want to 46 access this keyring through the normal methods, pass an empty string as the 47 identifier to the method. 48 49 See the \link app_keystore overview to the Password and Key Storage API 50 \endlink for an introduction to the API. 51 52 53 \since Haiku R1 54*/ 55 56 57/*! 58 \fn BKeyStore::BKeyStore() 59 \brief Create a new BKeyStore object that you can use to query, retrieve 60 and store keys in the system's key store. 61 62 This is a cheap object to make, as it has no data associated with it. The 63 recommended use is to create an instance on the stack whenever you want to 64 interact with the API. 65 66 \since Haiku R1 67*/ 68 69 70/*! 71 \fn virtual BKeyStore::~BKeyStore() 72 \brief Free all resources. 73 74 \since Haiku R1 75*/ 76 77/*! 78 \name Key Management 79*/ 80 81 82//! @{ 83 84 85/*! 86 \fn status_t BKeyStore::GetKey(BKeyType type, const char* identifier, 87 BKey& key) 88 \brief Query the Master keyring for for specific key. 89 90 This is a convenience method that calls \ref GetKey(const char* keyring, BKeyType type, const char* identifier, const char* secondaryIdentifier, bool secondaryIdentifierOptional, BKey& key). 91 92 It works on the Master \a keyring, and assumes an empty 93 \a secondaryIdentifier, \a secondaryIdentifierOptional set to \c false. 94 95 \since Haiku R1 96*/ 97 98 99/*! 100 \fn status_t BKeyStore::GetKey(BKeyType type, const char* identifier, 101 const char* secondaryIdentifier, BKey& key) 102 \brief Query the Master keyring for for specific key. 103 104 This is a convenience method that calls \ref GetKey(const char* keyring, BKeyType type, const char* identifier, const char* secondaryIdentifier, bool secondaryIdentifierOptional, BKey& key). 105 106 It works on the Master \a keyring, it sets \a secondaryIdentifierOptional 107 to \c false, meaning it both identifiers are required to match. 108 109 \since Haiku R1 110*/ 111 112 113/*! 114 \fn status_t BKeyStore::GetKey(BKeyType type, const char* identifier, 115 const char* secondaryIdentifier, bool secondaryIdentifierOptional, 116 BKey& key) 117 \brief Query the Master keyring for for specific key. 118 119 This is a convenience method that calls \ref GetKey(const char* keyring, BKeyType type, const char* identifier, const char* secondaryIdentifier, bool secondaryIdentifierOptional, BKey& key). 120 121 It works on the Master \a keyring. 122 123 \since Haiku R1 124*/ 125 126 127/*! 128 \fn status_t BKeyStore::GetKey(const char* keyring, BKeyType type, 129 const char* identifier, BKey& key) 130 \brief Query a certain \a keyring for for specific key. 131 132 This is a convenience method that calls \ref GetKey(const char* keyring, BKeyType type, const char* identifier, const char* secondaryIdentifier, bool secondaryIdentifierOptional, BKey& key). 133 134 The call assumes an empty \a secondaryIdentifier, and sets 135 \a secondaryIdentifierOptional to \c false. 136 137 \since Haiku R1 138*/ 139 140 141/*! 142 \fn status_t BKeyStore::GetKey(const char* keyring, BKeyType type, 143 const char* identifier, const char* secondaryIdentifier, BKey& key) 144 \brief Query a certain \a keyring for for specific key. 145 146 This is a convenience method that calls \ref GetKey(const char* keyring, BKeyType type, const char* identifier, const char* secondaryIdentifier, bool secondaryIdentifierOptional, BKey& key). 147 148 It sets \a secondaryIdentifierOptional to \c false, meaning it both 149 identifiers are required to match. 150 151 \since Haiku R1 152*/ 153 154 155/*! 156 \fn status_t BKeyStore::GetKey(const char* keyring, BKeyType type, 157 const char* identifier, const char* secondaryIdentifier, 158 bool secondaryIdentifierOptional, BKey& key) 159 \brief Query a certain \a keyring for for specific key. 160 161 This variation of the query function is useful when you know that a key has 162 a secondary identifier, but you may not know it, or care about what it is. 163 164 \param[in] keyring A string that identifies the keyring get the key from. 165 \param[in] type The type of key to match. The type parameter is currently 166 ignored and therefore does not need to match the actual type of the key 167 that is stored. 168 \param[in] identifier The string with the primary identifier of the key that 169 you are looking for. 170 \param[in] secondaryIdentifier The string with the secondary identifier of 171 the key that you are looking for. 172 \param[in] secondaryIdentifierOptional Use this query parameter to indicate 173 if the secondary identifier has to match. When set to \a false, a 174 result will be returned, even if the \a secondaryIdentifier does not 175 match. 176 \param[out] key A BKey object to copy the found data to. Any existing data 177 in the key will be overwritten in case there is a match. 178 179 \returns 180 - \c B_OK in case the key was found and stored in \a key. 181 - \c B_BAD_VALUE in case the \a keyring does not exist. 182 - \c B_NOT_ALLOWED in case the user did not grant you access right to 183 this \a keyring. 184 - \c B_ENTRY_NOT_FOUND in case there is no key that matches the given 185 identifier(s). 186 - Any other error that indicates that there was a problem communicating 187 with the \c keystore_server. 188 189 \since Haiku R1 190*/ 191 192 193/*! 194 \fn status_t BKeyStore::AddKey(const BKey& key) 195 \brief Add a \a key to the Master keyring 196 197 This is a convenience method that calls 198 \ref AddKey(const char *, const BKey&) for the \c Master keyring. 199 200 \since Haiku R1 201*/ 202 203 204/*! 205 \fn status_t BKeyStore::AddKey(const char* keyring, const BKey& key) 206 \brief Add a \a key to a \a keyring. 207 208 This method will send the key to the \c keystore_server and request it to 209 be stored in the database. 210 211 A key needs to have a unique primary and secondary identifier within the 212 Master keyring. 213 214 \param keyring A string that identifies the keyring you want to add the 215 key to. 216 \param key The key you want to add. 217 218 \returns 219 - \c B_OK in case the \a key was succesfully added. 220 - \c B_BAD_VALUE in case the \a keyring does not exist. 221 - \c B_NOT_ALLOWED in case the user did not grant you access right to 222 this \a keyring. 223 - \c B_NAME_IN_USE in case there already is another key with the same 224 primary and secondary identifiers. 225 - Any other error that indicates that there was a problem communicating 226 with the \c keystore_server. 227 228 \since Haiku R1 229*/ 230 231 232/*! 233 \fn status_t BKeyStore::RemoveKey(const BKey& key) 234 \brief Remove a \a key from the Master keyring. 235 236 This is a convenience method that calls 237 \ref RemoveKey(const char *, const BKey&) for the \c Master keyring. 238 239 \since Haiku R1 240*/ 241 242 243/*! 244 \fn status_t BKeyStore::RemoveKey(const char* keyring, const BKey& key) 245 \brief Remove a \a key from a \a keyring. 246 247 This method will remove a \a key from a \a keyring. The \a key needs to 248 match exactly with the key that is in the database of \c keystore_server. 249 The easiest way to guarantee this, is to use the exact key you find using 250 GetKey() without making any alterations. 251 252 \param keyring A string that identifies the keyring you want to remove 253 the key from. 254 \param key The key you want to remove. 255 256 \returns 257 - \c B_OK in case the \a key was succesfully removed. 258 - \c B_BAD_VALUE in case the \a keyring does not exist. 259 - \c B_NOT_ALLOWED in case the user did not grant you access right to 260 this \a keyring. 261 - \c B_ENTRY_NOT_FOUND in case there is no key that matches the given 262 identifier(s). 263 - Any other error that indicates that there was a problem communicating 264 with the \c keystore_server. 265 266 \since Haiku R1 267*/ 268 269 270/*! 271 \fn status_t BKeyStore::GetNextKey(uint32& cookie, BKey& key); 272 \brief Iterate through the keys of the Master keyring. 273 274 This convenience method that calls 275 \ref GetNextKey(const char*, BKeyType, BKeyPurpose, uint32&, BKey&) for the 276 Master keyring, with the arguments \ref BKeyType::B_KEY_TYPE_ANY for the 277 type and \ref BKeyPurpose::B_KEY_PURPOSE_ANY for the purpose. 278 279 \since Haiku R1 280*/ 281 282 283/*! 284 \fn status_t BKeyStore::GetNextKey(BKeyType type, BKeyPurpose purpose, 285 uint32& cookie, BKey& key) 286 \brief Iterate through the keys of the Master keyring. 287 288 This convenience method calls 289 \ref GetNextKey(const char*, BKeyType, BKeyPurpose, uint32&, BKey&) for the 290 Master keyring. 291 292 \since Haiku R1 293*/ 294 295 296/*! 297 \fn status_t BKeyStore::GetNextKey(const char* keyring, uint32& cookie, 298 BKey& key) 299 \brief Iterate through the keys of a \a keyring. 300 301 This convenience method calls 302 \ref GetNextKey(const char*, BKeyType, BKeyPurpose, uint32&, BKey&) with 303 the arguments \ref BKeyType::B_KEY_TYPE_ANY for the type and 304 \ref BKeyPurpose::B_KEY_PURPOSE_ANY for the purpose. 305 306 \since Haiku R1 307*/ 308 309 310/*! 311 \fn status_t BKeyStore::GetNextKey(const char* keyring, BKeyType type, 312 BKeyPurpose purpose, uint32& cookie, BKey& key) 313 \brief Iterate through keys of a \a keyring. 314 315 This method allows you to query through the key store, and iterate through 316 a list of results of keys that match your query. 317 318 \param[in] keyring An UTF-8 string that identifies the keyring 319 \param[in] type The BKeyType that identifies the type of key you are 320 looking for. This may be \ref BKeyType::B_KEY_TYPE_ANY if it may be a 321 key of any type. 322 \param[in] purpose The BKeyPurpose that indicates the purpose of the key. 323 This may be \ref BKeyPurpose::B_KEY_PURPOSE_ANY if it may be a key with 324 any purpose. 325 \param[out] cookie A cookie that the \c keystore_server uses to keep track 326 of where you are in the list of keys. When you start the query, set the 327 initial value to \c 0. After that, pass the cookie to each subsequent 328 call to progress the iterator. 329 \param[out] key The key that holds the data. Any existing data in the key 330 will be overwritten, when a key is found that matches the criteria. 331 332 \returns 333 - \c B_OK in case the next \a key was found. 334 - \c B_BAD_VALUE in case the \a keyring does not exist. 335 - \c B_NOT_ALLOWED in case the user did not grant you access right to 336 this \a keyring. 337 - \c B_ENTRY_NOT_FOUND in case there is no key that matches the given 338 identifier(s), or if you retrieved the last key. 339 - Any other error that indicates that there was a problem communicating 340 with the \c keystore_server. 341 342 \since Haiku R1 343*/ 344 345 346//! @} 347 348 349/*! 350 \name Keyrings 351*/ 352 353 354//! @{ 355 356 357/*! 358 \fn status_t BKeyStore::AddKeyring(const char* keyring) 359 \brief Create a new \a keyring. 360 361 \param keyring An UTF-8 string that identifies the keyring you want to 362 create. 363 364 \returns 365 - \c B_OK if the keyring was succesfully added. 366 - \c B_NAME_IN_USE if the \a keyring already exists. 367 - Any other error in case there was an unknown error in the 368 \c keystore_server, or while communicating to it. 369 370 \since Haiku R1 371*/ 372 373 374/*! 375 \fn status_t BKeyStore::RemoveKeyring(const char* keyring) 376 \brief Remove a \a keyring. 377 378 \param keyring An UTF-8 string that identifies the keyring you want to 379 remove. 380 381 \returns 382 - \c B_OK if the keyring was sucessfully removed. 383 - \c B_ENTRY_NOT_FOUND if the keyring does not exist 384 - \c B_NOT_ALLOWED when you try to remove the Master keyring. 385 - Any other error in case there was an unknown error in the 386 \c keystore_server, or while communicating to it. 387 388 \since Haiku R1 389*/ 390 391 392/*! 393 \fn status_t BKeyStore::GetNextKeyring(uint32& cookie, BString& keyring) 394 \brief Iterate through the keyrings. 395 396 \param[out] cookie A cookie that the \c keystore_server uses to keep track 397 of where you are in the list of keyrings. When you start the query, set 398 the initial value to \c 0. After that, pass the cookie to each 399 subsequent call to progress the iterator. 400 \param[out] keyring A BString that holds the current name of the keyring. 401 For each succesful iteration, the existing contents is overwritten. 402 403 \returns 404 - \c B_OK if the iteration was succesful. 405 - \c B_ENTRY_NOT_FOUND if there are no more keyrings left to iterate 406 - Any other error in case there was an unknown error in the 407 \c keystore_server, or while communicating to it. 408 409 \since Haiku R1 410*/ 411 412 413/*! 414 \fn status_t BKeyStore::SetUnlockKey(const char* keyring, const BKey& key) 415 \brief Not implemented. 416 417 This feature is not available in the current release of Haiku. 418*/ 419 420 421/*! 422 \fn status_t BKeyStore::RemoveUnlockKey(const char* keyring) 423 \brief Not implemented. 424 425 This feature is not available in the current release of Haiku. 426*/ 427 428 429//! @} 430 431 432/*! 433 \name Master keyring (future API) 434*/ 435 436 437//! @{ 438 439 440/*! 441 \fn status_t BKeyStore::SetMasterUnlockKey(const BKey& key) 442 \brief Not implemented. 443 444 This feature is not available in the current release of Haiku. 445*/ 446 447 448/*! 449 \fn status_t BKeyStore::RemoveMasterUnlockKey() 450 \brief Not implemented. 451 452 This feature is not available in the current release of Haiku. 453*/ 454 455 456/*! 457 \fn status_t BKeyStore::AddKeyringToMaster(const char* keyring) 458 \brief Not implemented. 459 460 This feature is not available in the current release of Haiku. 461 462 \see AddKeyring(const char* keyring) 463*/ 464 465 466/*! 467 \fn status_t BKeyStore::RemoveKeyringFromMaster(const char* keyring) 468 \brief Not implemented. 469 470 This feature is not available in the current release of Haiku. 471 472 \see RemoveKeyring(const char* keyring) 473*/ 474 475 476/*! 477 \fn status_t BKeyStore::GetNextMasterKeyring(uint32& cookie, 478 BString& keyring) 479 \brief Not implemented. 480 481 This feature is not available in the current release of Haiku. 482 483 \see GetNextKeyring(uint32& cookie, BString& keyring) 484*/ 485 486 487//! @} 488 489 490/*! 491 \name Locking (future API) 492 493 In the future, locking is part of encrypting and decrypting keyrings. 494 495 \note If you are looking at this section because you assume you need to 496 check that users have the correct permissions, you are in the wrong 497 place. There is no particular way to determine whether a user has 498 access granted. Instead, each method of this API will return the error 499 code \c B_NOT_ALLOWED if the user has not granted access. Use that in 500 your control flow to determine if you have access. 501*/ 502 503 504//! @{ 505 506 507/*! 508 \fn bool BKeyStore::IsKeyringUnlocked(const char* keyring) 509 \brief Not implemented. 510 511 This feature is not available in the current release of Haiku. 512*/ 513 514 515/*! 516 \fn status_t BKeyStore::LockKeyring(const char* keyring) 517 \brief Not implemented. 518 519 This feature is not available in the current release of Haiku. 520*/ 521 522 523/*! 524 \fn status_t BKeyStore::LockMasterKeyring() 525 \brief Not implemented. 526 527 This feature is not available in the current release of Haiku. 528*/ 529 530 531//! @} 532 533 534/*! 535 \name Applications 536*/ 537 538 539//! @{ 540 541 542/*! 543 \fn status_t BKeyStore::GetNextApplication(uint32& cookie, 544 BString& signature) const 545 \brief Iterate through applications that currently have been granted access 546 to the Master keyring. 547 548 This is a convenience method that calls 549 \ref GetNextApplication(const char* keyring, uint32& cookie, 550 BString& signature) for the Master \a keyring. 551 552 \since Haiku R1 553*/ 554 555 556/*! 557 \fn status_t BKeyStore::GetNextApplication(const char* keyring, 558 uint32& cookie, BString& signature) const 559 \brief Iterate through applications that currently have been granted access 560 to the specified \a keyring. 561 562 This method allows you to iterate through all applications that the user 563 has granted access to the \a keyring, whether it is temporarily, or on a 564 more permanent basis. 565 566 \param[in] keyring A UTF-8 string that identifies the keyring that you want 567 to inspect granted access to. 568 \param[out] cookie A cookie that the \c keystore_server uses to keep track 569 of where you are in the list of keys. When you start the query, set the 570 initial value to \c 0. After that, pass the cookie to each subsequent 571 call to progress the iterator. 572 \param[out] signature If a next application is found, the signature will be 573 stored in this parameter. Any existing string will be overwritten. 574 575 \returns 576 - \c B_OK if the next signature was found succesfully. 577 - \c B_BAD_VALUE if the keyring does not exist. 578 - \c B_NOT_ALLOWED in case the user did not grant you access right to 579 this \a keyring. 580 - \c B_ENTRY_NOT_FOUND if there are no more applications to iterate 581 through. 582 - Any other error in case there was an unknown error in the 583 \c keystore_server, or while communicating to it. 584 585 \since Haiku R1 586*/ 587 588 589/*! 590 \fn status_t BKeyStore::RemoveApplication(const char* signature) 591 \brief Remove access for an application to the Master keyring. 592 593 This is a convenience method that calls 594 \ref RemoveApplication(const char *, const char*) for the Master 595 \a keyring. 596 597 \since Haiku R1 598*/ 599 600 601/*! 602 \fn status_t BKeyStore::RemoveApplication(const char* keyring, 603 const char* signature) 604 \brief Remove access for an application to a \a keyring. 605 606 \param keyring A UTF-8 string that identifies the keyring that you want 607 to inspect granted access to. 608 \param signature The signature of the application that you want to revoke 609 permissions to access the keyring. 610 611 \returns 612 - \c B_OK if the application's access has been revoked. 613 - \c B_NOT_ALLOWED in case the user did not grant you access right to 614 this \a keyring. 615 - \c B_ENTRY_NOT_FOUND if the application did not have access to this 616 keyring. 617 - Any other error in case there was an unknown error in the 618 \c keystore_server, or while communicating to it. 619 620 \since Haiku R1 621*/ 622 623 624//! @} 625 626 627/*! 628 \name Service Functions (future API) 629 630 This feature is not available in the current release of Haiku. 631*/ 632 633 634//! @{ 635 636 637/*! 638 \fn status_t BKeyStore::GeneratePassword(BPasswordKey& password, 639 size_t length, uint32 flags) 640 \brief Unimplemented. 641 642 This method is currently not implemented. 643*/ 644 645 646/*! 647 \fn float BKeyStore::PasswordStrength(const char* password) 648 \brief Unimplemented 649 650 This method is currently not implemented 651*/ 652 653 654//! @} 655