passwords

Interact with Firefox's Password Manager to add, retrieve and remove stored credentials.

Usage

A credential is the set of information a user supplies to authenticate herself with a service. Typically a credential consists of a username and a password.

Using this module you can:

1. Search for credentials which have been stored in the Password Manager. You can then use the credentials to access their related service (for example, by logging into a web site).

2. Store credentials in the Password Manager. You can store different sorts of credentials, as outlined in the "Credentials" section below.

3. Remove stored credentials from the Password Manager.

Credentials

In this API, credentials are represented by objects.

You create credential objects to pass into the API, and the API also returns credential objects to you. The sections below explain both the properties you should define on credential objects and the properties you can expect on credential objects returned by the API.

All credential objects include username and password properties. Different sorts of stored credentials include various additional properties, as outlined in this section.

You can use the Passwords API with three sorts of credentials:

• Add-on credentials
• HTML form credentials
• HTTP Authentication credentials

Add-on Credential

These are associated with your add-on rather than a particular web site. They contain the following properties:

HTML Form Credential

If a web service uses HTML forms to authenticate its users, then the corresponding credential is an HTML Form credential.

It contains the following properties:

So: given a form at https://www.example.com/login with the following HTML:

<form action="https://login.example.com/foo/authenticate.cgi">
      <div>Please log in.</div>
      <label>Username:</label> <input type="text" name="uname">
      <label>Password:</label> <input type="password" name="pword">
</form>

The corresponding values for the credential (excluding username and password) should be:

  url: "https://www.example.com"
  formSubmitURL: "https://login.example.com"
  usernameField: "uname"
  passwordField: "pword"

Note that for both url and formSubmitURL, the portion of the URL after the hostname is omitted.

HTTP Authentication Credential

These are used to authenticate the user to a web site which uses HTTP Authentication, as detailed in RFC 2617. They contain the following properties:

So: if a web server at https://www.example.com requested authentication with a response code like this:

  HTTP/1.0 401 Authorization Required
  Server: Apache/1.3.27
  WWW-Authenticate: Basic realm="ExampleCo Login"

The corresponding values for the credential (excluding username and password) should be:

  url: "https://www.example.com"
  realm: "ExampleCo Login"

onComplete and onError

This API is explicitly asynchronous, so all its functions take two callback functions as additional options: onComplete and onError.

onComplete is called when the operation has completed successfully and onError is called when the function encounters an error.

Because the search function is expected to return a list of matching credentials, its onComplete option is mandatory. Because the other functions don't return a value in case of success their onComplete options are optional.

For all functions, onError is optional.

Globals

Functions

search(options)

This function is used to retrieve a credential, or a list of credentials, stored in the Password Manager.

You pass it any subset of the possible properties a credential can contain. Credentials which match all the properties you supplied are returned as an argument to the onComplete callback.

So if you pass in an empty set of properties, all stored credentials are returned:

function show_all_passwords() {
  require("sdk/passwords").search({
    onComplete: function onComplete(credentials) {
      credentials.forEach(function(credential) {
        console.log(credential.username);
        console.log(credential.password);
        });
      }
    });
  }

If you pass it a single property, only credentials matching that property are returned:

function show_passwords_for_joe() {
  require("sdk/passwords").search({
    username: "joe",
    onComplete: function onComplete(credentials) {
      credentials.forEach(function(credential) {
        console.log(credential.username);
        console.log(credential.password);
        });
      }
    });
  }

If you pass more than one property, returned credentials must match all of them:

function show_google_password_for_joe() {
  require("sdk/passwords").search({
    username: "joe",
    url: "https://www.google.com",
    onComplete: function onComplete(credentials) {
      credentials.forEach(function(credential) {
        console.log(credential.username);
        console.log(credential.password);
        });
      }
    });
  }

To retrieve only credentials associated with your add-on, use the url property, initialized from self.uri:

function show_my_addon_passwords() {
  require("sdk/passwords").search({
    url: require("sdk/self").uri,
    onComplete: function onComplete(credentials) {
      credentials.forEach(function(credential) {
        console.log(credential.username);
        console.log(credential.password);
        });
      }
    });
  }

Parameters

options : object
Required options:

Optional options:

store(options)

This function is used to store a credential in the Password Manager.

It takes an options object as an argument: this contains all the properties for the new credential.

As different sorts of credentials contain different properties, the appropriate options differ depending on the sort of credential being stored.

To store an add-on credential:

require("sdk/passwords").store({
  realm: "User Registration",
  username: "joe",
  password: "SeCrEt123",
});

To store an HTML form credential:

require("sdk/passwords").store({
  url: "https://www.example.com",
  formSubmitURL: "https://login.example.com",
  username: "joe",
  usernameField: "uname",
  password: "SeCrEt123",
  passwordField: "pword"
});

To store an HTTP Authentication credential:

require("sdk/passwords").store({
  url: "https://www.example.com",
  realm: "ExampleCo Login",
  username: "joe",
  password: "SeCrEt123",
});

See "Credentials" above for more details on how to set these properties.

The options parameter may also include onComplete and onError callback functions, which are called when the function has completed successfully and when it encounters an error, respectively. These options are both optional.

Parameters

options : object
Required options:

Optional options:

remove(options)

Removes a stored credential. You supply it all the properties of the credential to remove, along with optional onComplete and onError callbacks.

Because you must supply all the credential's properties, it may be convenient to call search first, and use its output as the input to remove. For example, to remove all of joe's stored credentials:

require("sdk/passwords").search({
  username: "joe",
  onComplete: function onComplete(credentials) {
    credentials.forEach(require("sdk/passwords").remove);
  })
});

To change an existing credential just call store after remove succeeds:

require("sdk/passwords").remove({
  realm: "User Registration",
  username: "joe",
  password: "SeCrEt123"
  onComplete: function onComplete() {
    require("sdk/passwords").store({
      realm: "User Registration",
      username: "joe",
      password: "{new password}"
    })
  }
});

Parameters

options : object
Required options:

Optional options: