0e6f95726d
The current implementation of the keystore_server is not perfect. While the source has many seeds for a future of having keyrings encrypted, and having more fine grained permissions, it is far from complete. The main arguments for adding documentation about this new but incomplete functionality is that while it is incomplete, the API is part of the public headers, and there are some legitimate use cases for developers. The documentation aims to give the proper amount of caution to any developer that is considering using this API. Change-Id: I154a3f8374b22dc6929758cba7ba810833bcfe9d
580 lines
13 KiB
Plaintext
580 lines
13 KiB
Plaintext
/*
|
|
* Copyright 2020 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Niels Sascha Reedijk, niels.reedijk@gmail.com
|
|
*
|
|
* Corresponds to:
|
|
* headers/os/app/Key.h hrev45343
|
|
* src/kits/app/Key.cpp hrev45343
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file Key.h
|
|
\ingroup app
|
|
\ingroup libbe
|
|
\brief Provides BKey and BPasswordKey classes, as well as BKeyPurpose and
|
|
BKeyType enums.
|
|
|
|
See the \link app_keystore overview to the Password and Key Storage API
|
|
\endlink for an introduction to the API.
|
|
|
|
*/
|
|
|
|
|
|
///// BKeyPurpose enum /////
|
|
|
|
|
|
/*!
|
|
\enum BKeyPurpose
|
|
\brief Descriptive constant for the purpose of the key
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BKeyPurpose::B_KEY_PURPOSE_ANY
|
|
\brief Query the key store for keys with any purpose.
|
|
|
|
This constant does not represent a key purpose by itself, but rather is
|
|
used in querying the key store where you do not know or care about the
|
|
purpose of key you are looking for.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BKeyPurpose::B_KEY_PURPOSE_GENERIC
|
|
\brief Generic key purpose
|
|
|
|
This type identifies keys that are not for a specific purpose.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BKeyPurpose::B_KEY_PURPOSE_KEYRING
|
|
\brief Keyring key purpose
|
|
|
|
This is a key purpose that is internal to the \c keystore_server. It
|
|
represents the internals of a keyring. You cannot directly access and
|
|
manipulate keys with this purpose. Instead you can use the methods on
|
|
\ref BKeyStore to access keys within keyrings.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BKeyPurpose::B_KEY_PURPOSE_WEB
|
|
\brief Web key purpose
|
|
|
|
This type refers to keys that are used on the web, such as username and
|
|
passwords for HTTP authentication, as well as for stored usernames and
|
|
passwords for form-based authentication.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BKeyPurpose::B_KEY_PURPOSE_NETWORK
|
|
\brief Network key purpose
|
|
|
|
This type refers to keys that are used in the networking stack, such as
|
|
WEP/WPA keys.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BKeyPurpose::B_KEY_PURPOSE_VOLUME
|
|
\brief Volume key purpose
|
|
|
|
This type refers to keys that are used to lock volumes, like password for
|
|
encryption.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
///// BKeyType enum /////
|
|
|
|
|
|
/*!
|
|
\enum BKeyType
|
|
\brief Descriptive constant for the type of a key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BKeyType::B_KEY_TYPE_ANY
|
|
\brief Query the key store for keys of any type
|
|
|
|
This constant does not represent a key type by itself, but rather is
|
|
used in querying the key store where you do not know or care about the
|
|
type of key you are looking for.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BKeyType::B_KEY_TYPE_GENERIC
|
|
\brief Generic key type.
|
|
|
|
This constant describes the type of key that does not have any particular
|
|
content or format. They are represented by the \ref BKey class.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BKeyType::B_KEY_TYPE_PASSWORD
|
|
\brief The key is a password.
|
|
|
|
This key type is represented by the \ref BPasswordKey class.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BKeyType::B_KEY_TYPE_CERTIFICATE
|
|
\brief The key is a certificate. Not in use.
|
|
|
|
This key type is for future expansion. It is currently not in use.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
///// BKey class /////
|
|
|
|
|
|
/*!
|
|
\class BKey
|
|
\ingroup app
|
|
\ingroup libbe
|
|
\brief Class that represents a generic key for or from the Haiku key
|
|
store
|
|
|
|
A key has the following properties:
|
|
- A key \b type of \ref BKeyType, which identifies the type. For a generic
|
|
key (like this key), it will be set to \ref BKeyType::B_KEY_TYPE_GENERIC.
|
|
- A key \b purpose of \ref BKeyPurpose, which identifies the purpose of the
|
|
key. This is a hint for your (or other) applications on how and where the
|
|
key may be used.
|
|
- A \b primary \b identifier that identifies a specific key. As an example,
|
|
for WPA passwords, this is set to the network name. This should be a
|
|
valid UTF-8 string.
|
|
- A \b secondary \b identifier that can be used as additional metadata.
|
|
- The \b data, the actual value of the key (such as a password or a
|
|
certificate). This should be a valid UTF-8 string.
|
|
- Not in use: the \b owner identifies who created and/or owns the key.
|
|
This feature is not yet enabled. It will always be set to an empty
|
|
string.
|
|
- Not in use: the \b creation \b time will indicate when a key was stored
|
|
in the central database. This feature is not yet enabled, and the value
|
|
will always be 0.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BKey::BKey();
|
|
\brief Constructor for an empty generic key.
|
|
|
|
An empty key has no data associated with it, other than that it has a
|
|
generic purpose and a generic key type.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BKey::BKey(BKeyPurpose purpose, const char* identifier,
|
|
const char* secondaryIdentifier = NULL, const uint8* data = NULL,
|
|
size_t length = 0)
|
|
\brief Constructor for a generic key with the provided data.
|
|
|
|
See the class introduction for more information about the properties of
|
|
a key. As you can see, the only required parameters are the \a purpose
|
|
and the \a identifier. Any data you provide will be copied into the BKey
|
|
object.
|
|
|
|
\param purpose The purpose of this key
|
|
\param identifier A unique identifier for this key
|
|
\param secondaryIdentifier An (optional) secondary identifier for this key
|
|
\param data A pointer to a buffer that contains the value of the key, such
|
|
as the password or the certificate data.
|
|
\param length The length of the data in bytes that should be copied.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BKey::BKey(BKey& other)
|
|
\brief Copy constructor that makes a copy of an \a other BKey.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn virtual BKey::~BKey()
|
|
\brief Free all resources associated with this key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn virtual BKeyType BKey::Type() const
|
|
\brief Returns the type of key.
|
|
|
|
For a generic BKey, this will always be \ref BKeyType::B_KEY_TYPE_GENERIC
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BKey::Unset()
|
|
\brief Reset the values of the key.
|
|
|
|
All properties of the key will be reset, except for the identifying owner.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BKey::SetTo(BKeyPurpose purpose, const char* identifier,
|
|
const char* secondaryIdentifier = NULL, const uint8* data = NULL,
|
|
size_t length = 0)
|
|
\brief Set the key to the specified values.
|
|
|
|
All properties of the key will be set to the parameters. If the key had a
|
|
creation time set, it will be cleared. If there was an owner set, this
|
|
piece of information will \em not be cleared.
|
|
|
|
\param purpose The purpose of this key
|
|
\param identifier A unique identifier for this key
|
|
\param secondaryIdentifier An (optional) secondary identifier for this key
|
|
\param data A pointer to a buffer that contains the value of the key, such
|
|
as the password or the certificate data.
|
|
\param length The length of the data in bytes that should be copied.
|
|
|
|
\returns
|
|
- \c B_OK if the changes were successful.
|
|
- \c B_NO_MEMORY in case it fails to allocate memory.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BKey::SetPurpose(BKeyPurpose purpose)
|
|
\brief Set the purpose of the key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BKeyPurpose BKey::Purpose() const
|
|
\brief Get the purpose of the key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BKey::SetIdentifier(const char* identifier)
|
|
\brief Set the identifier of the key.
|
|
|
|
\param identifier A pointer to a valid UTF-8 string.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn const char* BKey::Identifier() const
|
|
\brief Get the identifier of the key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BKey::SetSecondaryIdentifier(const char* identifier)
|
|
\brief Set the secondary identifier of the key.
|
|
|
|
\param identifier A pointer to a valid UTF-8 string.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn const char* BKey::SecondaryIdentifier() const
|
|
\brief Get the secondary identifier of the key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BKey::SetData(const uint8* data, size_t length)
|
|
\brief Set the data for the key.
|
|
|
|
\param data A pointer to the buffer that contains the data of the key.
|
|
\param length The length in bytes of the data.
|
|
|
|
\returns
|
|
- \c B_OK if the key data was updated.
|
|
- \c B_NO_MEMORY in case it fails to allocate memory.
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn size_t BKey::DataLength() const
|
|
\brief Get the size of the key in bytes.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn const uint8* BKey::Data() const
|
|
\brief Get a pointer to the data of the key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BKey::GetData(uint8* buffer, size_t bufferSize) const
|
|
\brief Copy the key into the \a buffer.
|
|
|
|
It is up to you to make sure the size of the buffer is the actual size of
|
|
the key's data. If the provided buffer is smaller, only the \a bufferSize
|
|
will be copied. If the buffer is larger, the key is copied, but the rest
|
|
of the buffer will not be touched.
|
|
|
|
\param[out] buffer The buffer to copy the key to.
|
|
\param[in] bufferSize The size of the provided \a buffer.
|
|
|
|
\returns
|
|
- \c B_OK if the data is sucessfully copied.
|
|
- An other error code if there was an issue copying the data.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn const char* BKey::Owner() const
|
|
\brief Get the owner of the key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bigtime_t BKey::CreationTime() const
|
|
\brief Get the creation time of the key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn virtual status_t BKey::Flatten(BMessage& message) const
|
|
\brief Flatten the key into a \a message.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn virtual status_t BKey::Unflatten(const BMessage& message)
|
|
\brief Unflatten the key from a \a message.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BKey& BKey::operator=(const BKey& other)
|
|
\brief Copy the data from the \a other key into this key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BKey::operator==(const BKey& other) const
|
|
\brief Compare this key to an \a other key.
|
|
|
|
\returns \c true if all the properties in both keys are identical.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BKey::operator!=(const BKey& other) const
|
|
\brief Compare this key to an \a other key.
|
|
|
|
\returns \c true if any of the properties in this key differ from \a other.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn virtual void BKey::PrintToStream()
|
|
\brief Dump the contents of the key to standard output.
|
|
|
|
This is a debug function that helps you read the contents of the key. All
|
|
properties, except for the actual \c data of the key, will be printed to
|
|
\c stdout.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
///// BPasswordKey class /////
|
|
|
|
|
|
/*!
|
|
\class BPasswordKey
|
|
\ingroup app
|
|
\ingroup libbe
|
|
\brief Class that represents a password for or from the Haiku key store.
|
|
|
|
This is a specialized version of the BKey class, which represents a key of
|
|
the \ref BKeyType::B_KEY_TYPE_PASSWORD.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
/*!
|
|
\fn BPasswordKey::BPasswordKey()
|
|
\brief Constructor for an empty password key.
|
|
|
|
An empty key has no data associated with it, other than that it has a
|
|
generic purpose and a password key type.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BPasswordKey::BPasswordKey(const char* password, BKeyPurpose purpose,
|
|
const char* identifier, const char* secondaryIdentifier = NULL)
|
|
\brief Constructor for a password key with the provided data.
|
|
|
|
See the BKey introduction for more information about the properties of
|
|
a key. As you can see, the only required parameters are the \a purpose
|
|
and the \a identifier. Any data you provide will be copied into the BKey
|
|
object.
|
|
|
|
\param password A null-terminated string that contains the password
|
|
\param purpose The purpose of this key
|
|
\param identifier A unique identifier for this key
|
|
\param secondaryIdentifier An (optional) secondary identifier for this key
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BPasswordKey::BPasswordKey(BPasswordKey& other)
|
|
\brief Copy constructor that makes a copy of an \a other BPasswordKey.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn virtual BPasswordKey::~BPasswordKey()
|
|
\brief Free all resources associated with this key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn virtual BKeyType BPasswordKey::Type() const
|
|
\brief Returns \ref BKeyType::B_KEY_TYPE_PASSWORD.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BPasswordKey::SetTo(const char* password, BKeyPurpose purpose,
|
|
const char* identifier, const char* secondaryIdentifier = NULL)
|
|
\brief Set the key to specific values.
|
|
|
|
All properties of the key will be set to the parameters. If the key had a
|
|
creation time set, it will be cleared. If there was an owner set, this
|
|
piece of information will \em not be cleared.
|
|
|
|
\param password A null-terminated string that contains the password
|
|
\param purpose The purpose of this key
|
|
\param identifier A unique identifier for this key
|
|
\param secondaryIdentifier An (optional) secondary identifier for this key
|
|
|
|
\returns
|
|
- \c B_OK if the changes were successful.
|
|
- \c B_NO_MEMORY in case it fails to allocate memory.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BPasswordKey::SetPassword(const char* password)
|
|
\brief Set the \a password for this key.
|
|
|
|
\param password A null-terminated string that contains the password.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn const char* BPasswordKey::Password() const
|
|
\brief Get the password for the key.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn virtual void BPasswordKey::PrintToStream()
|
|
\brief Dump the contents of the key to standard output.
|
|
|
|
This is a debug function that helps you read the contents of the key. All
|
|
properties, including the actual \b password, will be printed to \c stdout.
|
|
|
|
\since Haiku R1
|
|
*/
|