The BKeyStore lets you query, retrieve and store keys in the system's key store. More...

Public Member Functions
	BKeyStore ()
	Create a new BKeyStore object that you can use to query, retrieve and store keys in the system's key store.

virtual	~BKeyStore ()
	Free all resources.

Key Management
status_t	GetKey (BKeyType type, const char *identifier, BKey &key)
	Query the Master keyring for for specific key.

status_t	GetKey (BKeyType type, const char identifier, const char secondaryIdentifier, BKey &key)
	Query the Master keyring for for specific key.

status_t	GetKey (BKeyType type, const char identifier, const char secondaryIdentifier, bool secondaryIdentifierOptional, BKey &key)
	Query the Master keyring for for specific key.

status_t	GetKey (const char keyring, BKeyType type, const char identifier, BKey &key)
	Query a certain keyring for for specific key.

status_t	GetKey (const char keyring, BKeyType type, const char identifier, const char *secondaryIdentifier, BKey &key)
	Query a certain keyring for for specific key.

status_t	GetKey (const char keyring, BKeyType type, const char identifier, const char *secondaryIdentifier, bool secondaryIdentifierOptional, BKey &key)
	Query a certain keyring for for specific key.

status_t	AddKey (const BKey &key)
	Add a key to the Master keyring.

status_t	AddKey (const char *keyring, const BKey &key)
	Add a key to a keyring.

status_t	RemoveKey (const BKey &key)
	Remove a key from the Master keyring.

status_t	RemoveKey (const char *keyring, const BKey &key)
	Remove a key from a keyring.

status_t	GetNextKey (uint32 &cookie, BKey &key)
	Iterate through the keys of the Master keyring.

status_t	GetNextKey (BKeyType type, BKeyPurpose purpose, uint32 &cookie, BKey &key)
	Iterate through the keys of the Master keyring.

status_t	GetNextKey (const char *keyring, uint32 &cookie, BKey &key)
	Iterate through the keys of a keyring.

status_t	GetNextKey (const char *keyring, BKeyType type, BKeyPurpose purpose, uint32 &cookie, BKey &key)
	Iterate through keys of a keyring.

Keyrings
status_t	AddKeyring (const char *keyring)
	Create a new keyring.

status_t	RemoveKeyring (const char *keyring)
	Remove a keyring.

status_t	GetNextKeyring (uint32 &cookie, BString &keyring)
	Iterate through the keyrings.

status_t	SetUnlockKey (const char *keyring, const BKey &key)
	Not implemented.

status_t	RemoveUnlockKey (const char *keyring)
	Not implemented.

Master keyring (future API)
status_t	SetMasterUnlockKey (const BKey &key)
	Not implemented.

status_t	RemoveMasterUnlockKey ()
	Not implemented.

status_t	AddKeyringToMaster (const char *keyring)
	Not implemented.

status_t	RemoveKeyringFromMaster (const char *keyring)
	Not implemented.

status_t	GetNextMasterKeyring (uint32 &cookie, BString &keyring)
	Not implemented.

Locking (future API)
In the future, locking is part of encrypting and decrypting keyrings. Note If you are looking at this section because you assume you need to check that users have the correct permissions, you are in the wrong place. There is no particular way to determine whether a user has access granted. Instead, each method of this API will return the error code `B_NOT_ALLOWED` if the user has not granted access. Use that in your control flow to determine if you have access.
bool	IsKeyringUnlocked (const char *keyring)
	Not implemented.

status_t	LockKeyring (const char *keyring)
	Not implemented.

status_t	LockMasterKeyring ()
	Not implemented.

Applications
status_t	GetNextApplication (uint32 &cookie, BString &signature) const
	Iterate through applications that currently have been granted access to the Master keyring.

status_t	GetNextApplication (const char *keyring, uint32 &cookie, BString &signature) const
	Iterate through applications that currently have been granted access to the specified keyring.

status_t	RemoveApplication (const char *signature)
	Remove access for an application to the Master keyring.

status_t	RemoveApplication (const char keyring, const char signature)
	Remove access for an application to a keyring.

Service Functions (future API)
This feature is not available in the current release of Haiku.
status_t	GeneratePassword (BPasswordKey &password, size_t length, uint32 flags)
	Unimplemented.

float	PasswordStrength (const char *password)
	Unimplemented.

Detailed Description

The BKeyStore lets you query, retrieve and store keys in the system's key store.

Instances of this object give you an easy API to interact with the system's keystore_server. This is the central service that manages storing and retrieving keys, as well as managing the authorizations that a user grants to individual applications.

It is important to note that all calls on this object operate synchronously. This means that it should not be used during the event loop of a visible BWindow, as this may cause drawing and interaction issues.

All operations are performed in the context of a keyring. All systems have at least the Master keyring. Many of the methods take the name of the keyring as its first argument. Most of the methods in this class have an overloaded variant that operate on the Master keyring. If you want to access this keyring through the normal methods, pass an empty string as the identifier to the method.

See the overview to the Password and Key Storage API for an introduction to the API.

Since: Haiku R1

Constructor & Destructor Documentation

◆ BKeyStore()

BKeyStore::BKeyStore ( )

Create a new BKeyStore object that you can use to query, retrieve and store keys in the system's key store.

This is a cheap object to make, as it has no data associated with it. The recommended use is to create an instance on the stack whenever you want to interact with the API.

Since: Haiku R1

◆ ~BKeyStore()

BKeyStore::~BKeyStore ( )

virtual

Free all resources.

Since: Haiku R1

Member Function Documentation

◆ AddKey() [1/2]

status_t BKeyStore::AddKey ( const BKey & key )

Add a key to the Master keyring.

This is a convenience method that calls AddKey(const char *, const BKey&) for the Master keyring.

Since: Haiku R1

◆ AddKey() [2/2]

status_t BKeyStore::AddKey	(	const char *	keyring,
		const BKey &	key
	)

Add a key to a keyring.

This method will send the key to the keystore_server and request it to be stored in the database.

A key needs to have a unique primary and secondary identifier within the Master keyring.

Parameters

keyring	A string that identifies the keyring you want to add the key to.
key	The key you want to add.

Returns

B_OK in case the key was succesfully added.
B_BAD_VALUE in case the keyring does not exist.
B_NOT_ALLOWED in case the user did not grant you access right to this keyring.
B_NAME_IN_USE in case there already is another key with the same primary and secondary identifiers.
Any other error that indicates that there was a problem communicating with the keystore_server.

Since: Haiku R1

◆ AddKeyring()

status_t BKeyStore::AddKeyring ( const char * keyring )

Create a new keyring.

Parameters

keyring An UTF-8 string that identifies the keyring you want to create.

Returns

B_OK if the keyring was succesfully added.
B_NAME_IN_USE if the keyring already exists.
Any other error in case there was an unknown error in the keystore_server, or while communicating to it.

Since: Haiku R1

◆ AddKeyringToMaster()

status_t BKeyStore::AddKeyringToMaster ( const char * keyring )

Not implemented.

This feature is not available in the current release of Haiku.

See also: AddKeyring(const char* keyring)

◆ GeneratePassword()

status_t BKeyStore::GeneratePassword	(	BPasswordKey &	password,
		size_t	length,
		uint32	flags
	)

Unimplemented.

This method is currently not implemented.

◆ GetKey() [1/6]

status_t BKeyStore::GetKey	(	BKeyType	type,
		const char *	identifier,
		BKey &	key
	)

Query the Master keyring for for specific key.

This is a convenience method that calls GetKey(const char* keyring, BKeyType type, const char* identifier, const char* secondaryIdentifier, bool secondaryIdentifierOptional, BKey& key).

It works on the Master keyring, and assumes an empty secondaryIdentifier, secondaryIdentifierOptional set to false.

Since: Haiku R1

◆ GetKey() [2/6]

status_t BKeyStore::GetKey	(	BKeyType	type,
		const char *	identifier,
		const char *	secondaryIdentifier,
		BKey &	key
	)

Query the Master keyring for for specific key.

This is a convenience method that calls GetKey(const char* keyring, BKeyType type, const char* identifier, const char* secondaryIdentifier, bool secondaryIdentifierOptional, BKey& key).

It works on the Master keyring, it sets secondaryIdentifierOptional to false, meaning it both identifiers are required to match.

Since: Haiku R1

◆ GetKey() [3/6]

status_t BKeyStore::GetKey	(	BKeyType	type,
		const char *	identifier,
		const char *	secondaryIdentifier,
		bool	secondaryIdentifierOptional,
		BKey &	key
	)

Query the Master keyring for for specific key.

This is a convenience method that calls GetKey(const char* keyring, BKeyType type, const char* identifier, const char* secondaryIdentifier, bool secondaryIdentifierOptional, BKey& key).

It works on the Master keyring.

Since: Haiku R1

◆ GetKey() [4/6]

status_t BKeyStore::GetKey	(	const char *	keyring,
		BKeyType	type,
		const char *	identifier,
		BKey &	key
	)

Query a certain keyring for for specific key.

This is a convenience method that calls GetKey(const char* keyring, BKeyType type, const char* identifier, const char* secondaryIdentifier, bool secondaryIdentifierOptional, BKey& key).

The call assumes an empty secondaryIdentifier, and sets secondaryIdentifierOptional to false.

Since: Haiku R1

◆ GetKey() [5/6]

status_t BKeyStore::GetKey	(	const char *	keyring,
		BKeyType	type,
		const char *	identifier,
		const char *	secondaryIdentifier,
		BKey &	key
	)

Query a certain keyring for for specific key.

This is a convenience method that calls GetKey(const char* keyring, BKeyType type, const char* identifier, const char* secondaryIdentifier, bool secondaryIdentifierOptional, BKey& key).

It sets secondaryIdentifierOptional to false, meaning it both identifiers are required to match.

Since: Haiku R1

◆ GetKey() [6/6]

status_t BKeyStore::GetKey	(	const char *	keyring,
		BKeyType	type,
		const char *	identifier,
		const char *	secondaryIdentifier,
		bool	secondaryIdentifierOptional,
		BKey &	key
	)

Query a certain keyring for for specific key.

This variation of the query function is useful when you know that a key has a secondary identifier, but you may not know it, or care about what it is.

Parameters

[in]	keyring	A string that identifies the keyring get the key from.
[in]	type	The type of key to match. The type parameter is currently ignored and therefore does not need to match the actual type of the key that is stored.
[in]	identifier	The string with the primary identifier of the key that you are looking for.
[in]	secondaryIdentifier	The string with the secondary identifier of the key that you are looking for.
[in]	secondaryIdentifierOptional	Use this query parameter to indicate if the secondary identifier has to match. When set to false, a result will be returned, even if the secondaryIdentifier does not match.
[out]	key	A BKey object to copy the found data to. Any existing data in the key will be overwritten in case there is a match.

Returns

B_OK in case the key was found and stored in key.
B_BAD_VALUE in case the keyring does not exist.
B_NOT_ALLOWED in case the user did not grant you access right to this keyring.
B_ENTRY_NOT_FOUND in case there is no key that matches the given identifier(s).
Any other error that indicates that there was a problem communicating with the keystore_server.

Since: Haiku R1

◆ GetNextApplication() [1/2]

status_t BKeyStore::GetNextApplication	(	const char *	keyring,
		uint32 &	cookie,
		BString &	signature
	)		const

Iterate through applications that currently have been granted access to the specified keyring.

This method allows you to iterate through all applications that the user has granted access to the keyring, whether it is temporarily, or on a more permanent basis.

Parameters

[in]	keyring	A UTF-8 string that identifies the keyring that you want to inspect granted access to.
[out]	cookie	A cookie that the `keystore_server` uses to keep track of where you are in the list of keys. When you start the query, set the initial value to `0`. After that, pass the cookie to each subsequent call to progress the iterator.
[out]	signature	If a next application is found, the signature will be stored in this parameter. Any existing string will be overwritten.

Returns

B_OK if the next signature was found succesfully.
B_BAD_VALUE if the keyring does not exist.
B_NOT_ALLOWED in case the user did not grant you access right to this keyring.
B_ENTRY_NOT_FOUND if there are no more applications to iterate through.
Any other error in case there was an unknown error in the keystore_server, or while communicating to it.

Since: Haiku R1

◆ GetNextApplication() [2/2]

status_t BKeyStore::GetNextApplication	(	uint32 &	cookie,
		BString &	signature
	)		const

Iterate through applications that currently have been granted access to the Master keyring.

This is a convenience method that calls GetNextApplication(const char* keyring, uint32& cookie, BString& signature) for the Master keyring.

Since: Haiku R1

◆ GetNextKey() [1/4]

status_t BKeyStore::GetNextKey	(	BKeyType	type,
		BKeyPurpose	purpose,
		uint32 &	cookie,
		BKey &	key
	)

Iterate through the keys of the Master keyring.

This convenience method calls GetNextKey(const char*, BKeyType, BKeyPurpose, uint32&, BKey&) for the Master keyring.

Since: Haiku R1

◆ GetNextKey() [2/4]

status_t BKeyStore::GetNextKey	(	const char *	keyring,
		BKeyType	type,
		BKeyPurpose	purpose,
		uint32 &	cookie,
		BKey &	key
	)

Iterate through keys of a keyring.

This method allows you to query through the key store, and iterate through a list of results of keys that match your query.

Parameters

[in]	keyring	An UTF-8 string that identifies the keyring
[in]	type	The BKeyType that identifies the type of key you are looking for. This may be BKeyType::B_KEY_TYPE_ANY if it may be a key of any type.
[in]	purpose	The BKeyPurpose that indicates the purpose of the key. This may be BKeyPurpose::B_KEY_PURPOSE_ANY if it may be a key with any purpose.
[out]	cookie	A cookie that the `keystore_server` uses to keep track of where you are in the list of keys. When you start the query, set the initial value to `0`. After that, pass the cookie to each subsequent call to progress the iterator.
[out]	key	The key that holds the data. Any existing data in the key will be overwritten, when a key is found that matches the criteria.

Returns

B_OK in case the next key was found.
B_BAD_VALUE in case the keyring does not exist.
B_NOT_ALLOWED in case the user did not grant you access right to this keyring.
B_ENTRY_NOT_FOUND in case there is no key that matches the given identifier(s), or if you retrieved the last key.
Any other error that indicates that there was a problem communicating with the keystore_server.

Since: Haiku R1

◆ GetNextKey() [3/4]

status_t BKeyStore::GetNextKey	(	const char *	keyring,
		uint32 &	cookie,
		BKey &	key
	)

Iterate through the keys of a keyring.

This convenience method calls GetNextKey(const char*, BKeyType, BKeyPurpose, uint32&, BKey&) with the arguments BKeyType::B_KEY_TYPE_ANY for the type and BKeyPurpose::B_KEY_PURPOSE_ANY for the purpose.

Since: Haiku R1

◆ GetNextKey() [4/4]

status_t BKeyStore::GetNextKey	(	uint32 &	cookie,
		BKey &	key
	)

Iterate through the keys of the Master keyring.

This convenience method that calls GetNextKey(const char*, BKeyType, BKeyPurpose, uint32&, BKey&) for the Master keyring, with the arguments BKeyType::B_KEY_TYPE_ANY for the type and BKeyPurpose::B_KEY_PURPOSE_ANY for the purpose.

Since: Haiku R1

◆ GetNextKeyring()

status_t BKeyStore::GetNextKeyring	(	uint32 &	cookie,
		BString &	keyring
	)

Iterate through the keyrings.

Parameters

[out]	cookie	A cookie that the `keystore_server` uses to keep track of where you are in the list of keyrings. When you start the query, set the initial value to `0`. After that, pass the cookie to each subsequent call to progress the iterator.
[out]	keyring	A BString that holds the current name of the keyring. For each succesful iteration, the existing contents is overwritten.

Returns

B_OK if the iteration was succesful.
B_ENTRY_NOT_FOUND if there are no more keyrings left to iterate
Any other error in case there was an unknown error in the keystore_server, or while communicating to it.

Since: Haiku R1

◆ GetNextMasterKeyring()

status_t BKeyStore::GetNextMasterKeyring	(	uint32 &	cookie,
		BString &	keyring
	)

Not implemented.

This feature is not available in the current release of Haiku.

See also: GetNextKeyring(uint32& cookie, BString& keyring)

◆ IsKeyringUnlocked()

bool BKeyStore::IsKeyringUnlocked ( const char * keyring )

Not implemented.

This feature is not available in the current release of Haiku.

◆ LockKeyring()

status_t BKeyStore::LockKeyring ( const char * keyring )

Not implemented.

This feature is not available in the current release of Haiku.

◆ LockMasterKeyring()

status_t BKeyStore::LockMasterKeyring ( )

Not implemented.

This feature is not available in the current release of Haiku.

◆ PasswordStrength()

float BKeyStore::PasswordStrength ( const char * password )

Unimplemented.

This method is currently not implemented

◆ RemoveApplication() [1/2]

status_t BKeyStore::RemoveApplication	(	const char *	keyring,
		const char *	signature
	)

Remove access for an application to a keyring.

Parameters

keyring	A UTF-8 string that identifies the keyring that you want to inspect granted access to.
signature	The signature of the application that you want to revoke permissions to access the keyring.

Returns

B_OK if the application's access has been revoked.
B_NOT_ALLOWED in case the user did not grant you access right to this keyring.
B_ENTRY_NOT_FOUND if the application did not have access to this keyring.
Any other error in case there was an unknown error in the keystore_server, or while communicating to it.

Since: Haiku R1

◆ RemoveApplication() [2/2]

status_t BKeyStore::RemoveApplication ( const char * signature )

Remove access for an application to the Master keyring.

This is a convenience method that calls RemoveApplication(const char *, const char*) for the Master keyring.

Since: Haiku R1

◆ RemoveKey() [1/2]

status_t BKeyStore::RemoveKey ( const BKey & key )

Remove a key from the Master keyring.

This is a convenience method that calls RemoveKey(const char *, const BKey&) for the Master keyring.

Since: Haiku R1

◆ RemoveKey() [2/2]

status_t BKeyStore::RemoveKey	(	const char *	keyring,
		const BKey &	key
	)

Remove a key from a keyring.

This method will remove a key from a keyring. The key needs to match exactly with the key that is in the database of keystore_server. The easiest way to guarantee this, is to use the exact key you find using GetKey() without making any alterations.

Parameters

keyring	A string that identifies the keyring you want to remove the key from.
key	The key you want to remove.

Returns

B_OK in case the key was succesfully removed.
B_BAD_VALUE in case the keyring does not exist.
B_NOT_ALLOWED in case the user did not grant you access right to this keyring.
B_ENTRY_NOT_FOUND in case there is no key that matches the given identifier(s).
Any other error that indicates that there was a problem communicating with the keystore_server.

Since: Haiku R1

◆ RemoveKeyring()

status_t BKeyStore::RemoveKeyring ( const char * keyring )

Remove a keyring.

Parameters

keyring An UTF-8 string that identifies the keyring you want to remove.

Returns

B_OK if the keyring was sucessfully removed.
B_ENTRY_NOT_FOUND if the keyring does not exist
B_NOT_ALLOWED when you try to remove the Master keyring.
Any other error in case there was an unknown error in the keystore_server, or while communicating to it.

Since: Haiku R1

◆ RemoveKeyringFromMaster()

status_t BKeyStore::RemoveKeyringFromMaster ( const char * keyring )

Not implemented.

This feature is not available in the current release of Haiku.

See also: RemoveKeyring(const char* keyring)

◆ RemoveMasterUnlockKey()

status_t BKeyStore::RemoveMasterUnlockKey ( )

Not implemented.

This feature is not available in the current release of Haiku.

◆ RemoveUnlockKey()

status_t BKeyStore::RemoveUnlockKey ( const char * keyring )

Not implemented.

This feature is not available in the current release of Haiku.

◆ SetMasterUnlockKey()

status_t BKeyStore::SetMasterUnlockKey ( const BKey & key )

Not implemented.

This feature is not available in the current release of Haiku.

◆ SetUnlockKey()

status_t BKeyStore::SetUnlockKey	(	const char *	keyring,
		const BKey &	key
	)

Not implemented.

This feature is not available in the current release of Haiku.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BKeyStore()

◆ ~BKeyStore()

Member Function Documentation

◆ AddKey() [1/2]

◆ AddKey() [2/2]

◆ AddKeyring()

◆ AddKeyringToMaster()

◆ GeneratePassword()

◆ GetKey() [1/6]

◆ GetKey() [2/6]

◆ GetKey() [3/6]

◆ GetKey() [4/6]

◆ GetKey() [5/6]

◆ GetKey() [6/6]

◆ GetNextApplication() [1/2]

◆ GetNextApplication() [2/2]

◆ GetNextKey() [1/4]

◆ GetNextKey() [2/4]

◆ GetNextKey() [3/4]

◆ GetNextKey() [4/4]

◆ GetNextKeyring()

◆ GetNextMasterKeyring()

◆ IsKeyringUnlocked()

◆ LockKeyring()

◆ LockMasterKeyring()

◆ PasswordStrength()

◆ RemoveApplication() [1/2]

◆ RemoveApplication() [2/2]

◆ RemoveKey() [1/2]

◆ RemoveKey() [2/2]

◆ RemoveKeyring()

◆ RemoveKeyringFromMaster()

◆ RemoveMasterUnlockKey()

◆ RemoveUnlockKey()

◆ SetMasterUnlockKey()

◆ SetUnlockKey()