Class: Wx::SecretStore

Inherits:
Object
  • Object
show all
Defined in:
lib/wx/doc/gen/secret_store.rb,
lib/wx/doc/secret_store.rb

Overview

Note:

This class is untracked and should not be derived from nor instances extended!

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 SecretStore.get_default 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 developer.gnome.org/libsecret/) under Unix and may not be compiled in if it wasn’t found. You can check Wx::Setup::USE_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 #is_ok to check for this too. Example of storing credentials using this class:

store = Wx::SecretStore.get_default
  rc, err = store.ok?
  if rc
    unless store.save('MyApp/MyService', username, password)
      Wx.log_warning('Failed to save credentials to the system secret store.')
    end
  else
    Wx.log_warning("This system doesn't support storing passwords securely (#{err}).")
  end

And to load it back:

store = Wx::SecretStore.get_default
  rc, _ = store.ok?
  if rc
    password = Wx::SecretValue.new
    rc, username = store.load('MyApp/MyService', password)
    if rc
      # ... use the password ... 
    end
  end

Category: Miscellaneous

Requires:

  • USE_SECRETSTORE

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.get_default ⇒ Wx::SecretStore

Returns the default secrets collection to use.

Call #is_ok 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.

Returns:



53
 
# File 'lib/wx/doc/gen/secret_store.rb', line 53

def self.get_default; end

.wipe(secret) ⇒ void

This method returns an undefined value.

Wipes the secret data.

Parameters:

  • secret (String) —

    string containing secret data



15
 
# File 'lib/wx/doc/secret_store.rb', line 15

def self.wipe(secret); end

Instance Method Details

#delete(service) ⇒ Boolean

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.

Parameters:

  • service (String)

Returns:

  • (Boolean) 


87
 
# File 'lib/wx/doc/gen/secret_store.rb', line 87

def delete(service) end

#is_ok ⇒ Array(Boolean,String) Also known as: ok?

Check if this object can actually be used. Returns true if the object can be used. Returns false and an error message describing the reason if not.

Returns:

  • (Array(Boolean,String)) 


59
 
# File 'lib/wx/doc/gen/secret_store.rb', line 59

def is_ok; end

#load(service, password) ⇒ Array(Boolean,String)

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 the username and updates the provided password argument.

Parameters:

Returns:

  • (Array(Boolean,String)) 


80
 
# File 'lib/wx/doc/gen/secret_store.rb', line 80

def load(service, password) end

#save(service, username, password) ⇒ Boolean

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.

Parameters:

Returns:

  • (Boolean) 


71
 
# File 'lib/wx/doc/gen/secret_store.rb', line 71

def save(service, username, password) end