## Creating Password Providers

#### Extending Password Providers

When storing information (such as a CVS password) in the secure storage, the information gets encrypted with a master password. The interesting question about this process is how to store the master password?

The answer is in the password provider implementations. In a logical sense, password provider modules represent a trusted 3rd party, an external black box, which we trust to store our master password. That black box can be an operating system, some piece of hardware, or the user himself.

Several password provider modules are supplied with the SDK. They provide a basic "fallback" support and an improved support for some specific operating systems. For the most part you won't need to create a password provider - unless you'd like to add (or improve) integration with an operating system or add interaction with some specific hardware. In this case the set of password providers can be easily extended.

#### Declaring a Password Provider

The password provider modules have to be described as an extension to the extension point org.eclipse.equinox.security.secureStorage. The extension must specify an ID; the qualified ID of the extension will be used as an ID of the provider module and must not be changed between releases. The optional name and description of the password provider show up in the General > Security > Secure Storage preferences page and are visible to the end user.

Provider declaration includes the fully qualified class name that implements the provider, the numerical priority value, and a set of hints.

The priority is used to select a password provider when new data is added to the secure storage. The enabled provider with the highest priority is used by default. (Note that this can be overridden programmatically using IProviderHints#REQUIRED_MODULE_ID or by using the runtime option "-eclipse.password".)

The priority is an integer number from 0 to 10, with 10 being the highest priority. Consider adding your providers in the mid-range of priorities, 2 to 7, reserving top and bottom values.

An end user can disable a password provider via Secure Storage preferences page. Disabled providers are not considered when new data is added to the secure storage, but can be called on data retrieval if the data was originally encrypted with this provider.

Provider declaration can also specify a set of hints to help optimize interaction between the secure storage framework and the provider. The set of hints is open and can be extended in future. At the time of this writing the only expected hint is "AutomaticPasswordGeneration". This hint informs the framework that the password provider creates a master password without user interaction.

#### Implementing a Password Provider

The class implementing the password provider must extend the PasswordProvider class. The central point of that class is the getPassword() method that returns the master password for the provider for the current user. The method receives hints when a new password is expected to be created (as opposing to retrieving previously generated master password).

If your password provider has user interaction or has alternative paths to obtain the master password, you might consider overriding the PasswordProvider#retryOnError() method to inform the secure storage that the provider might be able to obtain a "better" password. For example, consider a password provider with the master password entered by the user. If the password entered was invalid, then the PasswordProvider#retryOnError() method will be consulted to see if the password provider can obtain a correct password.