| Version: 3.3.1

Public Member Functions | Static Public Member Functions | List of all members
wxSecretStore Class Reference
Class List by Category » Miscellaneous

`#include <wx/secretstore.h>`

## Detailed Description

A collection of secrets, sometimes called a key chain.

This class provides access to the secrets stored in the OS-provided facility, e.g. credentials manager under MSW, keychain under macOS or Freedesktop-compliant password storage mechanism such as GNOME keyring under Unix systems.

Currently only the access to the default keychain/ring is provided using GetDefault() method, support for other ones could be added in the future. After calling this method just call Save() to store a password entered by user and then call Load() to retrieve it during next program execution. See Secret Store Sample for an example of using this class.

The `service` parameter of the methods in this class should describe the purpose of the password and be unique to your program, e.g. it could be "MyCompany/MyProgram/SomeServer". Note that the server name must be included in the string to allow storing passwords for more than one server.

Notice that this class is always available under MSW (except when using MinGW32 which doesn't provide the required `wincred.h` header) and macOS but requires libsecret (see https://developer.gnome.org/libsecret/) under Unix and may not be compiled in if it wasn't found. You can check `wxUSE_SECRETSTORE` to test for this. Moreover, retrieving the default secret store may also fail under Unix during run-time if the desktop environment doesn't provide one, so don't forget to call IsOk() to check for this too.

Example of storing credentials using this class:

wxSecretStore store = wxSecretStore::GetDefault();
wxString errmsg;
if ( store.IsOk(&errmsg) )
{
if ( !store.Save("MyApp/MyService", username, password) )
wxLogWarning("Failed to save credentials to the system secret store.");
}
else
{
wxLogWarning("This system doesn't support storing passwords securely "
"(%s).", errmsg);
}
wxSecretStore
A collection of secrets, sometimes called a key chain.
Definition: secretstore.h:238
wxSecretStore::Save
bool Save(const wxString &service, const wxString &username, const wxSecretValue &password)
Store a username/password combination.
wxSecretStore::GetDefault
static wxSecretStore GetDefault()
Returns the default secrets collection to use.
wxSecretStore::IsOk
bool IsOk(wxString *errmsg=nullptr) const
Check if this object can actually be used.
wxString
String class for passing textual data to or receiving it from wxWidgets.
Definition: string.h:372
wxLogWarning
void wxLogWarning(const char *formatString,...)
For warnings - they are also normally shown to the user, but don't interrupt the program work.

And to load it back:

wxSecretStore store = wxSecretStore::GetDefault();
if ( store.IsOk() )
{
wxString username;
wxSecretValue password;
if ( store.Load("MyApp/MyService", username, password) )
... use the password ...
}
wxSecretStore::Load
bool Load(const wxString &service, wxString &username, wxSecretValue &password) const
Look up the username/password for the given service.
wxSecretValue
Represents the value of a secret in wxSecretStore.
Definition: secretstore.h:58

##

Library: wxBase
Category: Miscellaneous

Since
  3.1.1

## Public Member Functions
bool | IsOk (wxString *errmsg=nullptr) const
| Check if this object can actually be used. More...
bool | Save (const wxString &service, const wxString &username, const wxSecretValue &password)
| Store a username/password combination. More...
bool | Load (const wxString &service, wxString &username, wxSecretValue &password) const
| Look up the username/password for the given service. More...
bool | Delete (const wxString &service)
| Delete a previously stored username/password combination. More...

## Static Public Member Functions
static wxSecretStore | GetDefault ()
| Returns the default secrets collection to use. More...

## Member Function Documentation

## ◆ Delete()

bool wxSecretStore::Delete | ( | const wxString & | service | ) |

Delete a previously stored username/password combination.

If anything was deleted, returns true. Otherwise returns false and logs an error if any error other than not finding any matches occurred.

## ◆ GetDefault()

static wxSecretStore wxSecretStore::GetDefault | ( |  | ) |
| static

Returns the default secrets collection to use.

Call IsOk() on the returned object to check if this method succeeded.

Note that this method may show a dialog to the user under some platforms, so it can take an arbitrarily long time to return.

## ◆ IsOk()

bool wxSecretStore::IsOk | ( | wxString * | errmsg = `nullptr` | ) | const

Check if this object can actually be used.

Parameters

  errmsg | If not nullptr, this parameter is filled with a user-readable error message explaining why the secret store can't be used (this argument is new since wxWidgets 3.1.4)

## ◆ Load()

bool wxSecretStore::Load | ( | const wxString & | service,
|  | wxString & | username,
|  | wxSecretValue & | password
| ) |  | const

Look up the username/password for the given service.

If no username/password is found for the given service, false is returned.

Otherwise the function returns true and updates the provided username and password arguments.

## ◆ Save()

bool wxSecretStore::Save | ( | const wxString & | service,
|  | const wxString & | username,
|  | const wxSecretValue & | password
| ) |  |

Store a username/password combination.

The service name should be user readable and unique.

If a secret with the same service name already exists, it will be overwritten with the new value. In particular, notice that it is not currently allowed to store passwords for different usernames for the same service, even if the underlying platform API supports this (as is the case for macOS but not MSW).

Returns false after logging an error message if an error occurs, otherwise returns true indicating that the secret has been stored and can be retrieved by calling Load() later.