refactor!: consolidate crypto architecture and security model
* make ZeroEchoSession the sole policy, audit, and runtime boundary * replace combined key builders with operation-specific SPI and typed metadata * remove obsolete pre-release compatibility APIs and global crypto operations * finalize JCA agreement contexts and replace inheritance with composition * harden secret lifecycle, key destruction, hybrid KEX, PBKDF2, and audit handling * standardize PairSeq I/O and introduce immutable validated value types * migrate app, ext, samples, and required pki integration points * expand correctness, security, concurrency, and malformed-input coverage BREAKING CHANGE: removes deprecated pre-release global configuration, legacy context factories, combined key-builder contracts, String-based password APIs, unchecked PairSeq writing, BlockGeometry public fields, and other compatibility facades.
This commit is contained in:
@@ -1,93 +1,40 @@
|
||||
/*******************************************************************************
|
||||
* Copyright (C) 2026, Leo Galambos
|
||||
* All rights reserved.
|
||||
*
|
||||
*
|
||||
* Redistribution and use in source and binary forms, with or without modification,
|
||||
* are permitted provided that the following conditions are met:
|
||||
*
|
||||
* 1. Redistributions of source code must retain the above copyright notice, this
|
||||
* list of conditions and the following disclaimer.
|
||||
*
|
||||
* 2. Redistributions in binary form must reproduce the above copyright notice,
|
||||
* this list of conditions and the following disclaimer in the documentation
|
||||
* and/or other materials provided with the distribution.
|
||||
*
|
||||
* 3. All advertising materials mentioning features or use of this software must
|
||||
* display the following acknowledgement:
|
||||
* This product includes software developed by the Egothor project.
|
||||
*
|
||||
* 4. Neither the name of the copyright holder nor the names of its contributors
|
||||
* may be used to endorse or promote products derived from this software without
|
||||
* specific prior written permission.
|
||||
*
|
||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
||||
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||||
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
|
||||
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
|
||||
* ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
* are permitted provided that the conditions in the project LICENSE are met.
|
||||
******************************************************************************/
|
||||
package zeroecho.sdk.guard;
|
||||
|
||||
import java.util.Arrays;
|
||||
import java.util.Objects;
|
||||
import java.util.concurrent.locks.ReentrantLock;
|
||||
|
||||
import javax.security.auth.Destroyable;
|
||||
|
||||
import zeroecho.core.annotation.Describable;
|
||||
|
||||
/**
|
||||
* UnlockMaterial represents the unlocking data supplied to a recipient opener
|
||||
* to recover a content-encryption key (CEK).
|
||||
* Caller-owned session-operation input used to unlock a recipient entry.
|
||||
*
|
||||
* <h2>Overview</h2> The multi-recipient envelope scans recipient entries and
|
||||
* delegates each attempt to a {@code RecipientOpener}. An opener may require
|
||||
* either a private key or a password to unwrap or derive the CEK. This sealed
|
||||
* interface defines the two supported kinds of unlocking material and
|
||||
* centralizes their lifetime and handling.
|
||||
*
|
||||
* <h2>Usage</h2> <pre>{@code
|
||||
* // Decrypt with a private key
|
||||
* DataContent decRsa = new MultiRecipientDataSourceBuilder()
|
||||
* .withAes(AesDataContentBuilder.builder().modeGcm(128).withHeader())
|
||||
* .payloadKeyBytes(32)
|
||||
* .unlockWith(new UnlockMaterial.Private(rsaPrivateKey))
|
||||
* .build(false);
|
||||
*
|
||||
* // Decrypt with a password
|
||||
* char[] pwd = "correct horse battery staple".toCharArray();
|
||||
* DataContent decPwd = new MultiRecipientDataSourceBuilder()
|
||||
* .withAes(AesDataContentBuilder.builder().modeCbcPkcs7().withHeader())
|
||||
* .payloadKeyBytes(32)
|
||||
* .unlockWith(new UnlockMaterial.Password(pwd))
|
||||
* .build(false);
|
||||
* // Clear the password when no longer needed
|
||||
* java.util.Arrays.fill(pwd, '\0');
|
||||
* }</pre>
|
||||
*
|
||||
* <h2>Security notes</h2>
|
||||
* <ul>
|
||||
* <li>{@link Password} stores a reference to the caller-provided {@code char[]}
|
||||
* for performance and zeroization. The caller is responsible for clearing the
|
||||
* array after use.</li>
|
||||
* <li>{@link Private} holds a {@link java.security.PrivateKey}. Manage the
|
||||
* key's lifetime outside the opener and avoid logging or copying it
|
||||
* unnecessarily.</li>
|
||||
* </ul>
|
||||
* <p>Components accepting an {@code UnlockMaterial} borrow it and do not destroy
|
||||
* it. The caller must keep it usable until the operation completes and destroy
|
||||
* password material afterwards.</p>
|
||||
*/
|
||||
sealed public interface UnlockMaterial extends Describable {
|
||||
public sealed interface UnlockMaterial extends Describable {
|
||||
/**
|
||||
* Private holds a private key used to decrypt or decapsulate a recipient entry.
|
||||
* Private key unlocking material.
|
||||
*
|
||||
* <p>
|
||||
* Typical uses include RSA-OAEP decryption, ElGamal decryption, or KEM
|
||||
* decapsulation with a private KEM key.
|
||||
* </p>
|
||||
*
|
||||
* @param key the private key used by a matching {@code RecipientOpener}; must
|
||||
* not be null
|
||||
* @param key non-null private key
|
||||
*/
|
||||
record Private(java.security.PrivateKey key) implements UnlockMaterial, Describable {
|
||||
record Private(java.security.PrivateKey key) implements UnlockMaterial {
|
||||
/** Validates the key. */
|
||||
public Private {
|
||||
Objects.requireNonNull(key, "key must not be null");
|
||||
}
|
||||
|
||||
/** {@inheritDoc} */
|
||||
@Override
|
||||
public String description() {
|
||||
return "Unlock via key of " + key.getAlgorithm();
|
||||
@@ -95,23 +42,84 @@ sealed public interface UnlockMaterial extends Describable {
|
||||
}
|
||||
|
||||
/**
|
||||
* Password holds characters used to derive a key-encryption key (KEK) for
|
||||
* unwrapping the CEK.
|
||||
* Destroyable password unlocking material backed by an owned character array.
|
||||
*
|
||||
* <p>
|
||||
* The array reference is stored as provided to allow the caller to clear it
|
||||
* after use. If defensive copying is desired, the caller should provide a copy
|
||||
* and clear both copies after decryption.
|
||||
* </p>
|
||||
*
|
||||
* @param password the password characters; the caller should clear the array
|
||||
* when no longer needed
|
||||
* <p>Construction and access use defensive copies. Destruction is idempotent
|
||||
* and prevents subsequent access.</p>
|
||||
*/
|
||||
record Password(char[] password) implements UnlockMaterial, Describable {
|
||||
final class Password implements UnlockMaterial, Destroyable {
|
||||
private final char[] characters;
|
||||
private final ReentrantLock lifecycleLock = new ReentrantLock();
|
||||
private boolean destroyed;
|
||||
|
||||
/**
|
||||
* Creates password material from a caller-owned array.
|
||||
*
|
||||
* @param password source characters; retained only as a defensive copy
|
||||
* @throws NullPointerException if {@code password} is {@code null}
|
||||
*/
|
||||
@SuppressWarnings("PMD.UseVarargs")
|
||||
public Password(char[] password) {
|
||||
this.characters = Objects.requireNonNull(password, "password must not be null").clone();
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a caller-owned password copy.
|
||||
*
|
||||
* @return password copy
|
||||
* @throws IllegalStateException if destroyed
|
||||
*/
|
||||
public char[] password() {
|
||||
lifecycleLock.lock();
|
||||
try {
|
||||
if (destroyed) {
|
||||
throw new IllegalStateException("Password material has been destroyed");
|
||||
}
|
||||
return characters.clone();
|
||||
} finally {
|
||||
lifecycleLock.unlock();
|
||||
}
|
||||
}
|
||||
|
||||
/** {@inheritDoc} */
|
||||
@Override
|
||||
public String description() {
|
||||
return "Unlock via password";
|
||||
}
|
||||
|
||||
/** {@inheritDoc} */
|
||||
@Override
|
||||
public void destroy() {
|
||||
lifecycleLock.lock();
|
||||
try {
|
||||
if (!destroyed) {
|
||||
Arrays.fill(characters, '\0');
|
||||
destroyed = true;
|
||||
}
|
||||
} finally {
|
||||
lifecycleLock.unlock();
|
||||
}
|
||||
}
|
||||
|
||||
/** {@inheritDoc} */
|
||||
@Override
|
||||
public boolean isDestroyed() {
|
||||
lifecycleLock.lock();
|
||||
try {
|
||||
return destroyed;
|
||||
} finally {
|
||||
lifecycleLock.unlock();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a redacted diagnostic representation.
|
||||
*
|
||||
* @return redacted text
|
||||
*/
|
||||
@Override
|
||||
public String toString() {
|
||||
return "UnlockMaterial.Password[REDACTED]";
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user