org.netbeans.api.keyring.package-info Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/**
* 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 {@code org.netbeans.modules.keyring.impl},
* which offer the best combination of security and convenience:
*
* - Login-based encryption on Windows. (NetBeans physically stores the encrypted passwords.)
* - Mac OS X Keychain, using the default login keychain.
* - GNOME Keyring, using the default keyring (often unlocked by login).
* - 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 {@code PBEWithSHA1AndDESede} algorithm (SHA-1 / 3-DES) is used to encrypt
* passwords. It creates a random salt for the user using {@link java.security.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 {@code UUID}).
* The files in the user directory relating to this fallback keyring are marked
* {@code 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:
*
* - Avoid retaining passwords in instance fields reachable from GC roots other
* than the active stack frame if possible: get the password from {@link org.netbeans.api.keyring.Keyring#read},
* pass it on, and do not retain it.
* - Use {@code char[]} in preference to {@code String} where possible.
* This API works with {@code char[]} only.
* - Zero out a {@code char[]} password if you know you are done with it.
* See {@link org.netbeans.api.keyring.Keyring#read} and {@link org.netbeans.api.keyring.Keyring#save}
* for the behavior of this API.
*
*/
package org.netbeans.api.keyring;