Skip navigation links
org.netbeans.modules.keyring 1.34

Package org.netbeans.api.keyring

API for secure storage of user secrets such as passwords.

See: Description

Package org.netbeans.api.keyring Description

API for secure storage of user secrets such as passwords.

Rather than every module in a NetBeans-based application that needs to store passwords for repeated access having to write them to some file on disk using Base64 encoding or similar, this API permits passwords to be stored securely.

There are several platform-specific implementations of password storage currently available in a separate module org.netbeans.modules.keyring.impl, which offer the best combination of security and convenience:

  1. Login-based encryption on Windows. (NetBeans physically stores the encrypted passwords.)
  2. Mac OS X Keychain, using the default login keychain.
  3. GNOME Keyring, using the default keyring (often unlocked by login).
  4. KDE KWallet.

If none of these can be loaded, a fallback implementation is used which encrypts stored passwords using a single master password, as in e.g. Firefox. The user must pick a master password, then enter it once per session if the keyring is accessed. Java's PBEWithSHA1AndDESede algorithm (SHA-1 / 3-DES) is used to encrypt passwords. It creates a random salt for the user using SecureRandom. In addition to the passwords you ask to save, a sample string is saved to verify that an entered master password is correct: the sample must be decryptable and the decrypted value must begin with a magic sequence (the remainder having been generated randomly, again with UUID). The files in the user directory relating to this fallback keyring are marked go-w on Unix systems, to discourage brute-force cracking attempts on multiuser machines.

If even master password encryption is unavailable, due to missing security providers, or a headless AWT which makes dialogs impossible, or simply because the implementation module is not available, then a trivial implementation is used which just keeps passwords in memory for the duration of the JVM session.

Since Java lacks any API for secure non-pageable memory, please consider the following recommendations when working with passwords in memory:

  1. Avoid retaining passwords in instance fields reachable from GC roots other than the active stack frame if possible: get the password from Keyring.read(java.lang.String), pass it on, and do not retain it.
  2. Use char[] in preference to String where possible. This API works with char[] only.
  3. Zero out a char[] password if you know you are done with it. See Keyring.read(java.lang.String) and Keyring.save(java.lang.String, char[], java.lang.String) for the behavior of this API.
Skip navigation links
org.netbeans.modules.keyring 1.34