cwrsimon / java-keyring

Copy of Java Keyring library from bitbucket.org/bpsnervepoint -- with working CI in for osx/linux/windows keystore.

Status

Summary

java-keyring is a small library which provides a simple java API to store passwords and secrets securely in native os keystores.

Currently Mac OS X, Windows and Linux (GNOME) are supported.

History

Initially an abandoned bitbucket repo, but lotsa love has been given to it.

• Proper windows credential store access.
• Delete support.
• Solid testing.
• Automated builds in all target environements.

Initial repo: https://bitbucket.org/east301/java-keyring

Cloned from: https://bitbucket.org/bpsnervepoint/java-keyring

Implementation

Mac OS X

• Passwords are stored using OS X Keychain using Keychain Services api via "Legacy Password Storage".

Linux/Freedesktop

• Passwords are stored using DBus Secret Service, you probably used Seahorse. Connection is made via the excellent secret-service library.

Windows

• Passwords are stored using Credential Manager, exceptions will contain Error Codes. Access is via the Wincred api.

Usage

Dirt simple:

    Keyring keyring = Keyring.create();
    keyring.setPassword("domain", "account", "secret");
    String secret = keyring.getPassword("domain", "account");
    keyring.deletePassword("domain", "account");

Recommend creating a dummy value if getPassword() fails, so that users know where to go set the value in their applications.

    final Keyring keyring = Keyring.create();
    final String domain = "someDomain";
    final String account = "someAccount";
    try {
      return keyring.getPassword(domain, account);
    } catch ( PasswordAccessException ex ) {
      keyring.setPassword(domain, account, "ChangeMe");
      throw new RuntimeException("Please add the correct credentials to you keystore " 
          + keyring.getKeyringStorageType()
          + ". The credential is stored under '" + domain + "|" + account + "'"
          + "with a password that is currently 'ChangeMe'");
    }

Building

mvn clean install

License

Source code of java-keyring is available under a BSD license. See the file LICENSE.EAST301 for more details.

PRs are Welcome

Outstanding work:

• Windows error message conversion.
• Provide easy binding for Spring / CDI / etc.
• Support for build tools like Maven/Gradle.
• Perhaps optional UI requests for passwords (Wincred/secret-service have Apis at least to prompt users).
• Convert to Kotlin and test in different Kotlin build target (node/jvm/binary).
• Update the osx binding to use non-legacy apis.

That said, this library is perfectly usable today and tested on all systems. Checkout the badges above!

Special Thanks

java-keyring uses the following library, thanks a lot! java-keyring package contains copy of compiled JNA library. Source code of the library is available at its project page.

• Java native access (JNA)
• Secret Service