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/Key.h hrev45343 10 * src/kits/app/Key.cpp hrev45343 11 */ 12 13 14 /*! 15 \file Key.h 16 \ingroup app 17 \ingroup libbe 18 \brief Provides BKey and BPasswordKey classes, as well as BKeyPurpose and 19 BKeyType enums. 20 21 See the \link app_keystore overview to the Password and Key Storage API 22 \endlink for an introduction to the API. 23 24*/ 25 26 27 ///// BKeyPurpose enum ///// 28 29 30/*! 31 \enum BKeyPurpose 32 \brief Descriptive constant for the purpose of the key 33 34 \since Haiku R1 35*/ 36 37 38/*! 39 \var BKeyPurpose::B_KEY_PURPOSE_ANY 40 \brief Query the key store for keys with any purpose. 41 42 This constant does not represent a key purpose by itself, but rather is 43 used in querying the key store where you do not know or care about the 44 purpose of key you are looking for. 45 46 \since Haiku R1 47*/ 48 49 50/*! 51 \var BKeyPurpose::B_KEY_PURPOSE_GENERIC 52 \brief Generic key purpose 53 54 This type identifies keys that are not for a specific purpose. 55 56 \since Haiku R1 57*/ 58 59 60/*! 61 \var BKeyPurpose::B_KEY_PURPOSE_KEYRING 62 \brief Keyring key purpose 63 64 This is a key purpose that is internal to the \c keystore_server. It 65 represents the internals of a keyring. You cannot directly access and 66 manipulate keys with this purpose. Instead you can use the methods on 67 \ref BKeyStore to access keys within keyrings. 68 69 \since Haiku R1 70*/ 71 72 73/*! 74 \var BKeyPurpose::B_KEY_PURPOSE_WEB 75 \brief Web key purpose 76 77 This type refers to keys that are used on the web, such as username and 78 passwords for HTTP authentication, as well as for stored usernames and 79 passwords for form-based authentication. 80 81 \since Haiku R1 82*/ 83 84 85/*! 86 \var BKeyPurpose::B_KEY_PURPOSE_NETWORK 87 \brief Network key purpose 88 89 This type refers to keys that are used in the networking stack, such as 90 WEP/WPA keys. 91 92 \since Haiku R1 93*/ 94 95 96/*! 97 \var BKeyPurpose::B_KEY_PURPOSE_VOLUME 98 \brief Volume key purpose 99 100 This type refers to keys that are used to lock volumes, like password for 101 encryption. 102 103 \since Haiku R1 104*/ 105 106 107 ///// BKeyType enum ///// 108 109 110/*! 111 \enum BKeyType 112 \brief Descriptive constant for the type of a key. 113 114 \since Haiku R1 115*/ 116 117 118/*! 119 \var BKeyType::B_KEY_TYPE_ANY 120 \brief Query the key store for keys of any type 121 122 This constant does not represent a key type by itself, but rather is 123 used in querying the key store where you do not know or care about the 124 type of key you are looking for. 125 126 \since Haiku R1 127*/ 128 129 130/*! 131 \var BKeyType::B_KEY_TYPE_GENERIC 132 \brief Generic key type. 133 134 This constant describes the type of key that does not have any particular 135 content or format. They are represented by the \ref BKey class. 136 137 \since Haiku R1 138*/ 139 140 141/*! 142 \var BKeyType::B_KEY_TYPE_PASSWORD 143 \brief The key is a password. 144 145 This key type is represented by the \ref BPasswordKey class. 146 147 \since Haiku R1 148*/ 149 150 151/*! 152 \var BKeyType::B_KEY_TYPE_CERTIFICATE 153 \brief The key is a certificate. Not in use. 154 155 This key type is for future expansion. It is currently not in use. 156 157 \since Haiku R1 158*/ 159 160 161///// BKey class ///// 162 163 164/*! 165 \class BKey 166 \ingroup app 167 \ingroup libbe 168 \brief Class that represents a generic key for or from the Haiku key 169 store 170 171 A key has the following properties: 172 - A key \b type of \ref BKeyType, which identifies the type. For a generic 173 key (like this key), it will be set to \ref BKeyType::B_KEY_TYPE_GENERIC. 174 - A key \b purpose of \ref BKeyPurpose, which identifies the purpose of the 175 key. This is a hint for your (or other) applications on how and where the 176 key may be used. 177 - A \b primary \b identifier that identifies a specific key. As an example, 178 for WPA passwords, this is set to the network name. This should be a 179 valid UTF-8 string. 180 - A \b secondary \b identifier that can be used as additional metadata. 181 - The \b data, the actual value of the key (such as a password or a 182 certificate). This should be a valid UTF-8 string. 183 - Not in use: the \b owner identifies who created and/or owns the key. 184 This feature is not yet enabled. It will always be set to an empty 185 string. 186 - Not in use: the \b creation \b time will indicate when a key was stored 187 in the central database. This feature is not yet enabled, and the value 188 will always be 0. 189 190 \since Haiku R1 191*/ 192 193 194/*! 195 \fn BKey::BKey(); 196 \brief Constructor for an empty generic key. 197 198 An empty key has no data associated with it, other than that it has a 199 generic purpose and a generic key type. 200 201 \since Haiku R1 202*/ 203 204 205/*! 206 \fn BKey::BKey(BKeyPurpose purpose, const char* identifier, 207 const char* secondaryIdentifier = NULL, const uint8* data = NULL, 208 size_t length = 0) 209 \brief Constructor for a generic key with the provided data. 210 211 See the class introduction for more information about the properties of 212 a key. As you can see, the only required parameters are the \a purpose 213 and the \a identifier. Any data you provide will be copied into the BKey 214 object. 215 216 \param purpose The purpose of this key 217 \param identifier A unique identifier for this key 218 \param secondaryIdentifier An (optional) secondary identifier for this key 219 \param data A pointer to a buffer that contains the value of the key, such 220 as the password or the certificate data. 221 \param length The length of the data in bytes that should be copied. 222 223 \since Haiku R1 224*/ 225 226 227/*! 228 \fn BKey::BKey(BKey& other) 229 \brief Copy constructor that makes a copy of an \a other BKey. 230 231 \since Haiku R1 232*/ 233 234 235/*! 236 \fn virtual BKey::~BKey() 237 \brief Free all resources associated with this key. 238 239 \since Haiku R1 240*/ 241 242 243/*! 244 \fn virtual BKeyType BKey::Type() const 245 \brief Returns the type of key. 246 247 For a generic BKey, this will always be \ref BKeyType::B_KEY_TYPE_GENERIC 248 249 \since Haiku R1 250*/ 251 252 253/*! 254 \fn void BKey::Unset() 255 \brief Reset the values of the key. 256 257 All properties of the key will be reset, except for the identifying owner. 258 259 \since Haiku R1 260*/ 261 262 263/*! 264 \fn status_t BKey::SetTo(BKeyPurpose purpose, const char* identifier, 265 const char* secondaryIdentifier = NULL, const uint8* data = NULL, 266 size_t length = 0) 267 \brief Set the key to the specified values. 268 269 All properties of the key will be set to the parameters. If the key had a 270 creation time set, it will be cleared. If there was an owner set, this 271 piece of information will \em not be cleared. 272 273 \param purpose The purpose of this key 274 \param identifier A unique identifier for this key 275 \param secondaryIdentifier An (optional) secondary identifier for this key 276 \param data A pointer to a buffer that contains the value of the key, such 277 as the password or the certificate data. 278 \param length The length of the data in bytes that should be copied. 279 280 \returns 281 - \c B_OK if the changes were successful. 282 - \c B_NO_MEMORY in case it fails to allocate memory. 283 284 \since Haiku R1 285*/ 286 287 288/*! 289 \fn void BKey::SetPurpose(BKeyPurpose purpose) 290 \brief Set the purpose of the key. 291 292 \since Haiku R1 293*/ 294 295 296/*! 297 \fn BKeyPurpose BKey::Purpose() const 298 \brief Get the purpose of the key. 299 300 \since Haiku R1 301*/ 302 303 304/*! 305 \fn void BKey::SetIdentifier(const char* identifier) 306 \brief Set the identifier of the key. 307 308 \param identifier A pointer to a valid UTF-8 string. 309 310 \since Haiku R1 311*/ 312 313 314/*! 315 \fn const char* BKey::Identifier() const 316 \brief Get the identifier of the key. 317 318 \since Haiku R1 319*/ 320 321 322/*! 323 \fn void BKey::SetSecondaryIdentifier(const char* identifier) 324 \brief Set the secondary identifier of the key. 325 326 \param identifier A pointer to a valid UTF-8 string. 327 328 \since Haiku R1 329*/ 330 331 332/*! 333 \fn const char* BKey::SecondaryIdentifier() const 334 \brief Get the secondary identifier of the key. 335 336 \since Haiku R1 337*/ 338 339 340/*! 341 \fn status_t BKey::SetData(const uint8* data, size_t length) 342 \brief Set the data for the key. 343 344 \param data A pointer to the buffer that contains the data of the key. 345 \param length The length in bytes of the data. 346 347 \returns 348 - \c B_OK if the key data was updated. 349 - \c B_NO_MEMORY in case it fails to allocate memory. 350 \since Haiku R1 351*/ 352 353 354/*! 355 \fn size_t BKey::DataLength() const 356 \brief Get the size of the key in bytes. 357 358 \since Haiku R1 359*/ 360 361 362/*! 363 \fn const uint8* BKey::Data() const 364 \brief Get a pointer to the data of the key. 365 366 \since Haiku R1 367*/ 368 369 370/*! 371 \fn status_t BKey::GetData(uint8* buffer, size_t bufferSize) const 372 \brief Copy the key into the \a buffer. 373 374 It is up to you to make sure the size of the buffer is the actual size of 375 the key's data. If the provided buffer is smaller, only the \a bufferSize 376 will be copied. If the buffer is larger, the key is copied, but the rest 377 of the buffer will not be touched. 378 379 \param[out] buffer The buffer to copy the key to. 380 \param[in] bufferSize The size of the provided \a buffer. 381 382 \returns 383 - \c B_OK if the data is sucessfully copied. 384 - An other error code if there was an issue copying the data. 385 386 \since Haiku R1 387*/ 388 389 390/*! 391 \fn const char* BKey::Owner() const 392 \brief Get the owner of the key. 393 394 \since Haiku R1 395*/ 396 397 398/*! 399 \fn bigtime_t BKey::CreationTime() const 400 \brief Get the creation time of the key. 401 402 \since Haiku R1 403*/ 404 405 406/*! 407 \fn virtual status_t BKey::Flatten(BMessage& message) const 408 \brief Flatten the key into a \a message. 409 410 \since Haiku R1 411*/ 412 413 414/*! 415 \fn virtual status_t BKey::Unflatten(const BMessage& message) 416 \brief Unflatten the key from a \a message. 417 418 \since Haiku R1 419*/ 420 421 422/*! 423 \fn BKey& BKey::operator=(const BKey& other) 424 \brief Copy the data from the \a other key into this key. 425 426 \since Haiku R1 427*/ 428 429 430/*! 431 \fn bool BKey::operator==(const BKey& other) const 432 \brief Compare this key to an \a other key. 433 434 \returns \c true if all the properties in both keys are identical. 435 436 \since Haiku R1 437*/ 438 439 440/*! 441 \fn bool BKey::operator!=(const BKey& other) const 442 \brief Compare this key to an \a other key. 443 444 \returns \c true if any of the properties in this key differ from \a other. 445 446 \since Haiku R1 447*/ 448 449 450/*! 451 \fn virtual void BKey::PrintToStream() 452 \brief Dump the contents of the key to standard output. 453 454 This is a debug function that helps you read the contents of the key. All 455 properties, except for the actual \c data of the key, will be printed to 456 \c stdout. 457 458 \since Haiku R1 459*/ 460 461 462///// BPasswordKey class ///// 463 464 465/*! 466 \class BPasswordKey 467 \ingroup app 468 \ingroup libbe 469 \brief Class that represents a password for or from the Haiku key store. 470 471 This is a specialized version of the BKey class, which represents a key of 472 the \ref BKeyType::B_KEY_TYPE_PASSWORD. 473 474 \since Haiku R1 475*/ 476 477/*! 478 \fn BPasswordKey::BPasswordKey() 479 \brief Constructor for an empty password key. 480 481 An empty key has no data associated with it, other than that it has a 482 generic purpose and a password key type. 483 484 \since Haiku R1 485*/ 486 487 488/*! 489 \fn BPasswordKey::BPasswordKey(const char* password, BKeyPurpose purpose, 490 const char* identifier, const char* secondaryIdentifier = NULL) 491 \brief Constructor for a password key with the provided data. 492 493 See the BKey introduction for more information about the properties of 494 a key. As you can see, the only required parameters are the \a purpose 495 and the \a identifier. Any data you provide will be copied into the BKey 496 object. 497 498 \param password A null-terminated string that contains the password 499 \param purpose The purpose of this key 500 \param identifier A unique identifier for this key 501 \param secondaryIdentifier An (optional) secondary identifier for this key 502 503 \since Haiku R1 504*/ 505 506 507/*! 508 \fn BPasswordKey::BPasswordKey(BPasswordKey& other) 509 \brief Copy constructor that makes a copy of an \a other BPasswordKey. 510 511 \since Haiku R1 512*/ 513 514 515/*! 516 \fn virtual BPasswordKey::~BPasswordKey() 517 \brief Free all resources associated with this key. 518 519 \since Haiku R1 520*/ 521 522 523/*! 524 \fn virtual BKeyType BPasswordKey::Type() const 525 \brief Returns \ref BKeyType::B_KEY_TYPE_PASSWORD. 526 527 \since Haiku R1 528*/ 529 530 531/*! 532 \fn status_t BPasswordKey::SetTo(const char* password, BKeyPurpose purpose, 533 const char* identifier, const char* secondaryIdentifier = NULL) 534 \brief Set the key to specific values. 535 536 All properties of the key will be set to the parameters. If the key had a 537 creation time set, it will be cleared. If there was an owner set, this 538 piece of information will \em not be cleared. 539 540 \param password A null-terminated string that contains the password 541 \param purpose The purpose of this key 542 \param identifier A unique identifier for this key 543 \param secondaryIdentifier An (optional) secondary identifier for this key 544 545 \returns 546 - \c B_OK if the changes were successful. 547 - \c B_NO_MEMORY in case it fails to allocate memory. 548 549 \since Haiku R1 550*/ 551 552 553/*! 554 \fn status_t BPasswordKey::SetPassword(const char* password) 555 \brief Set the \a password for this key. 556 557 \param password A null-terminated string that contains the password. 558 559 \since Haiku R1 560*/ 561 562 563/*! 564 \fn const char* BPasswordKey::Password() const 565 \brief Get the password for the key. 566 567 \since Haiku R1 568*/ 569 570 571/*! 572 \fn virtual void BPasswordKey::PrintToStream() 573 \brief Dump the contents of the key to standard output. 574 575 This is a debug function that helps you read the contents of the key. All 576 properties, including the actual \b password, will be printed to \c stdout. 577 578 \since Haiku R1 579*/ 580