Egothor/ZeroEcho
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

feat: PKI module core design

Browse Source 
Signed-off-by: Leo Galambos <lg@hq.egothor.org>
This commit is contained in:
Leo Galambos
2025-12-27 21:38:32 +01:00
parent 276ac91eb4
commit 7673e7d82f
138 changed files with 10033 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
pki/.classpath Normal file
View File

@@ -0,0 +1,31 @@
<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="src" output="bin/main" path="src/main/java">
<attributes>
<attribute name="gradle_scope" value="main"/>
<attribute name="gradle_used_by_scope" value="main,test"/>
</attributes>
</classpathentry>
<classpathentry kind="src" output="pki/bin/main" path="src/main/resources"/>
<classpathentry kind="src" output="bin/test" path="src/test/java">
<attributes>
<attribute name="test" value="true"/>
<attribute name="gradle_scope" value="test"/>
<attribute name="gradle_used_by_scope" value="test"/>
</attributes>
</classpathentry>
<classpathentry kind="src" output="bin/test" path="src/test/resources">
<attributes>
<attribute name="test" value="true"/>
<attribute name="gradle_scope" value="test"/>
<attribute name="gradle_used_by_scope" value="test"/>
</attributes>
</classpathentry>
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-21/">
<attributes>
<attribute name="module" value="true"/>
</attributes>
</classpathentry>
<classpathentry kind="con" path="org.eclipse.buildship.core.gradleclasspathcontainer"/>
<classpathentry kind="output" path="bin/default"/>
</classpath>

23
pki/.project Normal file
View File

@@ -0,0 +1,23 @@
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>pki</name>
<comment>Project pki created by Buildship.</comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.jdt.core.javabuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.buildship.core.gradleprojectbuilder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.jdt.core.javanature</nature>
<nature>org.eclipse.buildship.core.gradleprojectnature</nature>
</natures>
</projectDescription>

31
pki/LICENSE Normal file
View File

@@ -0,0 +1,31 @@
Copyright (C) 2025, 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.

57
pki/build.gradle Normal file
View File

@@ -0,0 +1,57 @@
plugins {
id 'buildlogic.java-application-conventions'
id 'com.palantir.git-version'
}
group 'org.egothor'
dependencies {
implementation 'org.apache.commons:commons-text'
implementation 'commons-cli:commons-cli'
implementation project(':lib')
}
application {
// Define the main class for the application.
mainClass = 'zeroecho.pki.PkiApplication'
}
jar {
manifest {
attributes(
'Main-Class': application.mainClass,
'Implementation-Title': rootProject.name,
'Implementation-Version': "${version}"
)
}
from sourceSets.main.output
dependsOn configurations.runtimeClasspath
// Include each JAR dependency
configurations.runtimeClasspath.findAll { it.exists() && it.name.endsWith('.jar') }.each { jarFile ->
def jarName = jarFile.name.replaceAll(/\.jar$/, '')
from(zipTree(jarFile)) {
// Exclude signature-related files
exclude 'META-INF/*.SF', 'META-INF/*.DSA', 'META-INF/*.RSA'
// Rename license/notice files to avoid conflicts
eachFile { file ->
if (file.path ==~ /META-INF\/(LICENSE|NOTICE)(\..*)?/) {
file.path = "META-INF/licenses-from-${jarName}/${file.name}"
}
}
includeEmptyDirs = false
}
}
duplicatesStrategy = DuplicatesStrategy.EXCLUDE
}
javadoc {
options.links("https://www.egothor.org/javadoc/zeroecho/lib")
}

99
pki/src/main/java/zeroecho/pki/PkiApplication.java Normal file
View File

@@ -0,0 +1,99 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki;
import java.util.Objects;
import java.util.logging.Level;
import java.util.logging.Logger;
/**
* Minimal bootstrap entry point for the {@code pki} module.
*
* <p>
* This class is intentionally limited to process bootstrap concerns only:
* </p>
* <ul>
* <li>initializes JUL logging conventions (without leaking secrets),</li>
* <li>installs an uncaught-exception handler,</li>
* <li>emits a minimal startup/shutdown signal.</li>
* </ul>
*
* <p>
* No cryptography, persistence, or domain/business logic is performed here. The
* public PKI API resides under {@code zeroecho.pki.api.*} and is not modified
* by this bootstrap.
* </p>
*/
public final class PkiApplication {
private static final Logger LOG = Logger.getLogger(PkiApplication.class.getName());
private PkiApplication() {
throw new AssertionError("No instances.");
}
/**
* Starts the PKI process.
*
* <p>
* Security note: command-line arguments are not logged because they can contain
* sensitive material (paths, tokens, passphrases).
* </p>
*
* @param args command-line arguments (never logged)
*/
public static void main(String[] args) {
Objects.requireNonNull(args, "args");
PkiLogging.configureIfPresent();
PkiLogging.installUncaughtExceptionHandler();
LOG.info("ZeroEcho PKI starting.");
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
Logger shutdownLogger = Logger.getLogger(PkiApplication.class.getName());
PkiLogging.emitShutdownMessage(shutdownLogger, "ZeroEcho PKI stopping.");
}, "zeroecho-pki-shutdown"));
try {
// Intentionally no business logic yet. Bootstrap only.
LOG.info("ZeroEcho PKI started (bootstrap only).");
} catch (RuntimeException ex) {
// Do not include user-provided inputs in the message; log the exception object.
LOG.log(Level.SEVERE, "Fatal error during PKI bootstrap.", ex);
throw ex;
}
}
}

180
pki/src/main/java/zeroecho/pki/PkiLogging.java Normal file
View File

@@ -0,0 +1,180 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki;
import java.io.IOException;
import java.io.InputStream;
import java.lang.Thread.UncaughtExceptionHandler;
import java.util.Objects;
import java.util.logging.Level;
import java.util.logging.LogManager;
import java.util.logging.Logger;
/**
* Internal bootstrap utilities for JUL configuration in the {@code pki} module.
*
* <p>
* This helper intentionally avoids logging any potentially sensitive material.
* In particular, it never logs:
* </p>
* <ul>
* <li>command-line arguments,</li>
* <li>key material, seeds, shared secrets,</li>
* <li>private configuration values (tokens, passphrases).</li>
* </ul>
*
* <p>
* Configuration strategy:
* </p>
* <ul>
* <li>If a {@code /zeroecho-pki-logging.properties} resource is present on the
* classpath, it will be loaded via
* {@link LogManager#readConfiguration(InputStream)}.</li>
* <li>If not present, JUL defaults remain in place (minimal bootstrap
* behavior).</li>
* </ul>
*/
final class PkiLogging {
/**
* Optional classpath resource for JUL configuration.
*/
static final String LOGGING_PROPERTIES_RESOURCE = "/zeroecho-pki-logging.properties";
private static final Logger LOG = Logger.getLogger(PkiLogging.class.getName());
private static volatile boolean configured;
private PkiLogging() {
throw new AssertionError("No instances.");
}
/**
* Configures JUL from an optional classpath resource, if present.
*
* <p>
* This method is idempotent and safe to call multiple times.
* </p>
*/
static void configureIfPresent() {
if (configured) {
return;
}
synchronized (PkiLogging.class) {
if (configured) {
return;
}
InputStream in = PkiLogging.class.getResourceAsStream(LOGGING_PROPERTIES_RESOURCE);
if (in == null) {
configured = true;
return;
}
try (InputStream is = in) {
LogManager.getLogManager().readConfiguration(is);
configured = true;
LOG.info("JUL configured from classpath resource.");
} catch (IOException ex) {
configured = true;
// Keep message generic; do not leak environment specifics.
LOG.log(Level.WARNING, "Failed to load JUL configuration; continuing with defaults.", ex);
}
}
}
/**
* Installs a process-wide uncaught exception handler that logs failures via
* JUL.
*
* <p>
* The handler emits a generic message and includes the throwable. It
* deliberately does not serialize additional contextual data that might contain
* secrets.
* </p>
*/
static void installUncaughtExceptionHandler() {
UncaughtExceptionHandler handler = (Thread thread, Throwable throwable) -> {
Objects.requireNonNull(thread, "thread");
Objects.requireNonNull(throwable, "throwable");
Logger logger = Logger.getLogger(PkiApplication.class.getName());
logger.log(Level.SEVERE, "Uncaught exception in thread: " + thread.getName(), throwable);
};
Thread.setDefaultUncaughtExceptionHandler(handler);
}
/**
* Emits a shutdown message in a way that remains visible even during late JVM
* teardown.
*
* <p>
* The primary path is JUL. As a fallback, a constant message is written to
* {@code System.err}. This avoids logging any secrets and improves reliability
* in environments where JUL output may be lost during shutdown.
* </p>
*
* @param logger logger to use for the primary JUL emission
* @param message message to emit; must not contain secrets
* @throws NullPointerException if {@code logger} or {@code message} is
* {@code null}
*/
static void emitShutdownMessage(Logger logger, String message) {
Objects.requireNonNull(logger, "logger");
Objects.requireNonNull(message, "message");
// Primary path: JUL
logger.info(message);
// Flush root handlers (covers parent-handler delegation).
Logger root = Logger.getLogger("");
for (java.util.logging.Handler handler : root.getHandlers()) {
try {
handler.flush();
} catch (RuntimeException ignored) {
// Never throw during shutdown
}
}
// Fallback: direct stderr write
try {
System.err.println(message);
System.err.flush();
} catch (RuntimeException ignored) {
// Never throw during shutdown
}
}
}

83
pki/src/main/java/zeroecho/pki/api/BackupService.java Normal file
View File

@@ -0,0 +1,83 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import zeroecho.pki.api.backup.BackupArtifact;
import zeroecho.pki.api.backup.BackupRequest;
import zeroecho.pki.api.backup.BackupVerificationReport;
import zeroecho.pki.api.backup.RestoreReport;
import zeroecho.pki.api.backup.RestoreRequest;
/**
* Backup/restore operations for PKI state.
*
* <p>
* Backups must not implicitly include private keys. Private keys are referenced
* via {@link KeyRef} and may be managed by separate components.
* </p>
*/
public interface BackupService {
/**
* Creates a backup of PKI state.
*
* @param request backup request
* @return backup artifact
* @throws IllegalArgumentException if {@code request} is invalid
* @throws PkiException if backup creation fails
*/
BackupArtifact createBackup(BackupRequest request);
/**
* Restores PKI state from a backup artifact.
*
* @param request restore request
* @return restore report
* @throws IllegalArgumentException if {@code request} is invalid
* @throws PkiException if restore fails
*/
RestoreReport restoreBackup(RestoreRequest request);
/**
* Verifies a backup artifact for structural validity and integrity.
*
* @param artifact backup artifact
* @return verification report
* @throws IllegalArgumentException if {@code artifact} is null
* @throws PkiException if verification fails due to IO/backend
* errors
*/
BackupVerificationReport verifyBackup(BackupArtifact artifact);
}

172
pki/src/main/java/zeroecho/pki/api/CaService.java Normal file
View File

@@ -0,0 +1,172 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import java.util.List;
import zeroecho.pki.api.ca.CaCreateCommand;
import zeroecho.pki.api.ca.CaImportCommand;
import zeroecho.pki.api.ca.CaKeyRotationCommand;
import zeroecho.pki.api.ca.CaQuery;
import zeroecho.pki.api.ca.CaRecord;
import zeroecho.pki.api.ca.CaRolloverCommand;
import zeroecho.pki.api.ca.CaState;
import zeroecho.pki.api.ca.IntermediateCertIssueCommand;
import zeroecho.pki.api.ca.IntermediateCreateCommand;
import zeroecho.pki.api.credential.Credential;
/**
* Manages Certificate Authority (CA) entities and their lifecycle.
*
* <p>
* A CA entity represents an administrative unit capable of issuing credentials.
* A CA entity may own multiple CA credentials over time to support
* cross-signing, rollover, and key rotation.
* </p>
*
* <p>
* Private key material is never handled directly by the PKI module; the CA key
* is referenced by {@link KeyRef} and resolved by runtime wiring.
* </p>
*/
public interface CaService {
/**
* Creates a new root CA entity and issues its initial CA credential.
*
* @param command create command defining subject/profile and optional key
* reference
* @return created CA identifier
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if creation fails due to policy, storage, or
* framework backend error
*/
PkiId createRoot(CaCreateCommand command);
/**
* Imports an existing root CA into the PKI inventory.
*
* <p>
* This registers a CA entity, associates it with a {@link KeyRef}, and persists
* the existing CA credential. Import does not automatically imply trust; trust
* anchor selection is a consumer decision.
* </p>
*
* @param command import command including CA credential payload and key
* reference
* @return imported CA identifier
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if import fails (e.g., inconsistent
* metadata, storage failure)
*/
PkiId importRoot(CaImportCommand command);
/**
* Creates a new intermediate CA entity and issues its initial intermediate CA
* credential.
*
* @param command intermediate creation command
* @return created intermediate CA identifier
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if creation fails
*/
PkiId createIntermediate(IntermediateCreateCommand command);
/**
* Issues a new CA credential for an existing intermediate CA entity.
*
* <p>
* This operation enables cross-signing and renewal scenarios.
* </p>
*
* @param command issuance command specifying issuer and subject CA entity
* @return newly issued CA credential
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if issuance fails due to policy or backend
* errors
*/
Credential issueIntermediateCertificate(IntermediateCertIssueCommand command);
/**
* Performs a CA credential rollover while keeping the same key reference.
*
* @param command rollover command
* @return CA identifier (same CA id expected; returned for convenience)
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if rollover fails
*/
PkiId rolloverCaCertificate(CaRolloverCommand command);
/**
* Rotates the CA key reference and issues new corresponding CA credentials.
*
* @param command key rotation command
* @return CA identifier (same CA id expected; returned for convenience)
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if rotation fails
*/
PkiId rotateCaKey(CaKeyRotationCommand command);
/**
* Updates CA operational state.
*
* @param caId CA identifier
* @param state new CA state
* @param reason non-empty operator-readable reason suitable for audit
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if CA does not exist or update fails
*/
void setCaState(PkiId caId, CaState state, String reason);
/**
* Retrieves a CA record.
*
* @param caId CA identifier
* @return CA record
* @throws IllegalArgumentException if {@code caId} is invalid
* @throws PkiException if CA does not exist
*/
CaRecord getCa(PkiId caId);
/**
* Lists CA records matching query constraints.
*
* @param query query constraints
* @return list of CA records
* @throws IllegalArgumentException if {@code query} is invalid
* @throws PkiException if listing fails
*/
List<CaRecord> listCas(CaQuery query);
}

123
pki/src/main/java/zeroecho/pki/api/CertificationRequestService.java Normal file
View File

@@ -0,0 +1,123 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import java.util.List;
import java.util.Optional;
import zeroecho.pki.api.issuance.VerificationPolicy;
import zeroecho.pki.api.request.CertificationRequest;
import zeroecho.pki.api.request.ParsedCertificationRequest;
import zeroecho.pki.api.request.ProofOfPossessionResult;
import zeroecho.pki.api.request.RequestQuery;
import zeroecho.pki.api.request.RequestStorePolicy;
/**
* Processes certification requests (CSR-like objects) into a normalized
* representation.
*
* <p>
* This service provides request fingerprinting, parsing, proof-of-possession
* verification, and optional persistence for correlation and auditing. Request
* transport protocols such as ACME are expected to use this service as the core
* processing layer.
* </p>
*/
public interface CertificationRequestService {
/**
* Computes a stable identifier (fingerprint) for the given request payload.
*
* @param request certification request
* @return stable request identifier
* @throws IllegalArgumentException if {@code request} is null
* @throws PkiException if fingerprinting fails
*/
PkiId fingerprint(CertificationRequest request);
/**
* Parses and normalizes a certification request.
*
* @param request certification request
* @return parsed request
* @throws IllegalArgumentException if {@code request} is null
* @throws PkiException if parsing fails (invalid request,
* unsupported format, backend failure)
*/
ParsedCertificationRequest parse(CertificationRequest request);
/**
* Verifies proof-of-possession (PoP) for the private key corresponding to the
* requested public key.
*
* @param parsed parsed request
* @param policy verification policy
* @return PoP verification result
* @throws IllegalArgumentException if inputs are null
* @throws PkiException if verification fails due to backend failure
*/
ProofOfPossessionResult verifyProofOfPossession(ParsedCertificationRequest parsed, VerificationPolicy policy);
/**
* Stores a parsed request for later correlation and audit.
*
* @param parsed parsed request
* @param policy storage policy
* @return stored request id
* @throws IllegalArgumentException if inputs are null
* @throws PkiException if persistence fails
*/
PkiId store(ParsedCertificationRequest parsed, RequestStorePolicy policy);
/**
* Retrieves a stored request.
*
* @param requestId request id
* @return parsed request if present
* @throws IllegalArgumentException if {@code requestId} is null
* @throws PkiException if retrieval fails
*/
Optional<ParsedCertificationRequest> get(PkiId requestId);
/**
* Searches stored requests.
*
* @param query request query
* @return matching requests
* @throws IllegalArgumentException if {@code query} is null
* @throws PkiException if searching fails
*/
List<ParsedCertificationRequest> search(RequestQuery query);
}

101
pki/src/main/java/zeroecho/pki/api/CredentialInventoryService.java Normal file
View File

@@ -0,0 +1,101 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import java.time.Instant;
import java.util.List;
import java.util.Optional;
import zeroecho.pki.api.credential.Credential;
import zeroecho.pki.api.credential.CredentialQuery;
import zeroecho.pki.api.credential.CredentialStatus;
/**
* Inventory and reporting service for issued credentials.
*/
public interface CredentialInventoryService {
/**
* Retrieves a credential by id.
*
* @param credentialId credential id
* @return credential if present
* @throws IllegalArgumentException if {@code credentialId} is null
* @throws PkiException if retrieval fails
*/
Optional<Credential> get(PkiId credentialId);
/**
* Finds a credential by issuer CA and serial/unique identifier.
*
* @param issuerCaId issuer CA id
* @param serialOrUniqueId serial/unique id
* @return credential if present
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if lookup fails
*/
Optional<Credential> findByIssuerSerial(PkiId issuerCaId, String serialOrUniqueId);
/**
* Lists credentials bound to the same public key identifier.
*
* @param publicKeyId public key id
* @return credentials
* @throws IllegalArgumentException if {@code publicKeyId} is null
* @throws PkiException if lookup fails
*/
List<Credential> listByPublicKeyId(PkiId publicKeyId);
/**
* Searches credentials by query constraints.
*
* @param query query constraints
* @return matching credentials
* @throws IllegalArgumentException if {@code query} is null
* @throws PkiException if search fails
*/
List<Credential> search(CredentialQuery query);
/**
* Computes credential status at a given time.
*
* @param credentialId credential id
* @param now evaluation time
* @return computed status
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if evaluation fails
*/
CredentialStatus computeStatus(PkiId credentialId, Instant now);
}

72
pki/src/main/java/zeroecho/pki/api/EncodedObject.java Normal file
View File

@@ -0,0 +1,72 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
/**
* Immutable container for an encoded artifact.
*
* <p>
* This type intentionally carries only the {@link Encoding} and raw bytes. It
* does not carry a media type, because DER/PEM/BINARY do not uniquely determine
* the semantic meaning (a DER payload may represent a certificate, CSR, CRL,
* etc.). The semantic meaning is carried by the surrounding API context.
* </p>
*
* <p>
* Security note: implementations must never log the raw bytes in full.
* </p>
*
* @param encoding encoding kind
* @param bytes non-empty payload bytes
*/
public record EncodedObject(Encoding encoding, byte[] bytes) {
/**
* Creates an encoded object.
*
* @param encoding encoding kind
* @param bytes non-empty payload bytes
* @throws IllegalArgumentException if {@code encoding} is null or {@code bytes}
* is null/empty
*/
public EncodedObject {
if (encoding == null) {
throw new IllegalArgumentException("encoding must not be null");
}
if (bytes == null || bytes.length == 0) {
throw new IllegalArgumentException("bytes must not be null/empty");
}
}
}

75
pki/src/main/java/zeroecho/pki/api/Encoding.java Normal file
View File

@@ -0,0 +1,75 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
/**
* Specifies the encoding of a binary artifact payload.
*
* <p>
* The encoding indicates how the {@code bytes} inside {@link EncodedObject}
* should be interpreted. The logical meaning of the payload (certificate vs CSR
* vs CRL vs backup) is defined by the surrounding API context and record types.
* </p>
*/
public enum Encoding {
/**
* ASN.1 Distinguished Encoding Rules (DER).
*
* <p>
* Common for X.509 certificates, CRLs, and PKCS#10 certification requests.
* </p>
*/
DER,
/**
* PEM armored textual representation.
*
* <p>
* Typically base64-wrapped DER with header/footer lines.
* </p>
*/
PEM,
/**
* Raw binary blob without implying ASN.1 DER or PEM semantics.
*
* <p>
* Use for non-ASN.1 frameworks (e.g., COSE/JWS) or container payloads (e.g.,
* backup archives).
* </p>
*/
BINARY
}

64
pki/src/main/java/zeroecho/pki/api/FormatId.java Normal file
View File

@@ -0,0 +1,64 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
/**
* Identifier of a credential framework/format handled by the PKI core.
*
* <p>
* Examples: {@code "x509"}, {@code "ssh"}, {@code "cose"}, {@code "jws"}.
* </p>
*
* <p>
* This identifier is used to dispatch operations to a framework backend
* implementation.
* </p>
*
* @param value non-empty format identifier string
*/
public record FormatId(String value) {
/**
* Creates a format identifier.
*
* @param value non-empty format identifier string
* @throws IllegalArgumentException if {@code value} is null or blank
*/
public FormatId {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("value must not be null/blank");
}
}
}

122
pki/src/main/java/zeroecho/pki/api/ImportExportService.java Normal file
View File

@@ -0,0 +1,122 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import zeroecho.pki.api.revocation.RevokedRecord;
import zeroecho.pki.api.transfer.ExportArtifact;
import zeroecho.pki.api.transfer.ExportFormat;
import zeroecho.pki.api.transfer.ExportQuery;
import zeroecho.pki.api.transfer.ImportPolicy;
/**
* Import and export operations for migration and interoperability.
*
* <p>
* Import does not imply trust; it is a controlled operation governed by policy.
* Import/export is expected to be auditable.
* </p>
*/
public interface ImportExportService {
/**
* Imports an issued credential payload into inventory.
*
* @param formatId credential format id
* @param credential encoded credential payload
* @param policy import policy
* @return imported credential id
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if import fails
*/
PkiId importCredential(FormatId formatId, EncodedObject credential, ImportPolicy policy);
/**
* Imports a CA certificate payload into an existing CA entity's credential set.
*
* @param caId CA entity id
* @param caCertificate CA certificate payload
* @param policy import policy
* @return imported credential id
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if import fails
*/
PkiId importCaCertificate(PkiId caId, EncodedObject caCertificate, ImportPolicy policy);
/**
* Imports a revocation record.
*
* @param record revocation record
* @param policy import policy
* @return imported revocation record id (implementation-defined)
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if import fails
*/
PkiId importRevocation(RevokedRecord record, ImportPolicy policy);
/**
* Exports credentials matching the query constraints in the requested export
* format.
*
* @param query export query
* @param format export format
* @return export artifact
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if export fails
*/
ExportArtifact exportCredentials(ExportQuery query, ExportFormat format);
/**
* Exports revocation records matching the query constraints in the requested
* export format.
*
* @param query export query
* @param format export format
* @return export artifact
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if export fails
*/
ExportArtifact exportRevocations(ExportQuery query, ExportFormat format);
/**
* Exports CA materials for a given CA entity in the requested export format.
*
* @param caId CA entity id
* @param format export format
* @return export artifact
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if export fails
*/
ExportArtifact exportCa(PkiId caId, ExportFormat format);
}

108
pki/src/main/java/zeroecho/pki/api/IssuanceService.java Normal file
View File

@@ -0,0 +1,108 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import zeroecho.pki.api.credential.CredentialBundle;
import zeroecho.pki.api.issuance.BundleCommand;
import zeroecho.pki.api.issuance.IssueEndEntityCommand;
import zeroecho.pki.api.issuance.ReissueCommand;
import zeroecho.pki.api.issuance.RenewCommand;
import zeroecho.pki.api.issuance.ReplaceCommand;
/**
* Issues, renews, replaces, and reissues credentials, and builds distributable
* bundles.
*
* <p>
* This service is framework-agnostic: concrete credential formats are
* implemented by framework backends. The PKI runtime applies policy and profile
* constraints before calling issuance backends.
* </p>
*/
public interface IssuanceService {
/**
* Issues a new end-entity credential.
*
* @param command issuance command
* @return credential bundle (credential plus supporting artifacts)
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if issuance fails
*/
CredentialBundle issueEndEntity(IssueEndEntityCommand command);
/**
* Renews an existing credential according to policy-defined continuity
* semantics.
*
* @param command renewal command
* @return renewed credential bundle
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if renewal fails
*/
CredentialBundle renew(RenewCommand command);
/**
* Replaces an existing credential (e.g., after compromise or attribute
* changes).
*
* @param command replacement command
* @return replacement credential bundle
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if replacement fails
*/
CredentialBundle replace(ReplaceCommand command);
/**
* Reissues based on a stored issuance record.
*
* @param command reissue command
* @return reissued credential bundle
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if reissue fails
*/
CredentialBundle reissue(ReissueCommand command);
/**
* Builds a distributable bundle for an existing credential using chain
* selection rules.
*
* @param command bundle command
* @return bundle
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if bundle building fails
*/
CredentialBundle buildBundle(BundleCommand command);
}

55
pki/src/main/java/zeroecho/pki/api/IssuerRef.java Normal file
View File

@@ -0,0 +1,55 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
/**
* References an issuing CA entity.
*
* @param caId identifier of the CA entity acting as issuer
*/
public record IssuerRef(PkiId caId) {
/**
* Creates an issuer reference.
*
* @param caId CA identifier
* @throws IllegalArgumentException if {@code caId} is null
*/
public IssuerRef {
if (caId == null) {
throw new IllegalArgumentException("caId must not be null");
}
}
}

62
pki/src/main/java/zeroecho/pki/api/KeyRef.java Normal file
View File

@@ -0,0 +1,62 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
/**
* Opaque reference to private key material.
*
* <p>
* The PKI module never handles private key bytes. A {@link KeyRef} is resolved
* by runtime wiring, e.g., by a crypto component, an HSM adapter, or a remote
* signer. Implementations must treat this reference as sensitive metadata and
* avoid logging it unnecessarily.
* </p>
*
* @param value non-empty key reference token
*/
public record KeyRef(String value) {
/**
* Creates a key reference.
*
* @param value non-empty key reference token
* @throws IllegalArgumentException if {@code value} is null or blank
*/
public KeyRef {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("value must not be null/blank");
}
}
}

82
pki/src/main/java/zeroecho/pki/api/PkiException.java Normal file
View File

@@ -0,0 +1,82 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
/**
* Base runtime exception for PKI domain failures.
*
* <p>
* This exception is used to report policy violations, storage failures,
* framework backend errors, and other domain-level problems not representable
* as {@link IllegalArgumentException}.
* </p>
*
* <p>
* Security note: exception messages must not contain secrets (private keys,
* plaintext, shared secrets, or other sensitive cryptographic material).
* </p>
*/
public class PkiException extends RuntimeException {
private static final long serialVersionUID = 759504279718537161L;
/**
* Creates a PKI exception with a message.
*
* @param message non-empty message describing the failure in a non-sensitive
* manner
*/
public PkiException(String message) {
super(requireNonBlank(message, "message"));
}
/**
* Creates a PKI exception with a message and cause.
*
* @param message non-empty message describing the failure in a non-sensitive
* manner
* @param cause underlying cause
*/
public PkiException(String message, Throwable cause) {
super(requireNonBlank(message, "message"), cause);
}
private static String requireNonBlank(String value, String name) {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException(name + " must not be null/blank");
}
return value;
}
}

65
pki/src/main/java/zeroecho/pki/api/PkiId.java Normal file
View File

@@ -0,0 +1,65 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
/**
* Opaque identifier for PKI-managed entities.
*
* <p>
* Instances of this type are used as stable references for CA entities,
* credentials, certification requests, status objects, backups, publications,
* exports, and policy/audit records.
* </p>
*
* <p>
* The value must be treated as an opaque token and persisted verbatim.
* </p>
*
* @param value non-empty identifier string
*/
public record PkiId(String value) {
/**
* Creates an opaque PKI identifier.
*
* @param value non-empty identifier string
* @throws IllegalArgumentException if {@code value} is null or blank
*/
public PkiId {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("value must not be null/blank");
}
}
}

82
pki/src/main/java/zeroecho/pki/api/PolicyService.java Normal file
View File

@@ -0,0 +1,82 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import zeroecho.pki.api.issuance.IssuanceInputs;
import zeroecho.pki.api.policy.PolicyDecision;
import zeroecho.pki.api.policy.PolicyTrace;
import zeroecho.pki.api.revocation.RevocationInputs;
/**
* Policy evaluation and explainability.
*
* <p>
* Policy decisions must be deterministic, auditable, and explainable.
* Implementations are expected to provide traces suitable for operator
* troubleshooting and compliance evidence.
* </p>
*/
public interface PolicyService {
/**
* Evaluates an issuance request against policy and profile constraints.
*
* @param inputs normalized issuance inputs
* @return policy decision
* @throws IllegalArgumentException if {@code inputs} is null
* @throws PkiException if evaluation fails
*/
PolicyDecision evaluateIssuance(IssuanceInputs inputs);
/**
* Evaluates a revocation request against policy constraints.
*
* @param inputs normalized revocation inputs
* @return policy decision
* @throws IllegalArgumentException if {@code inputs} is null
* @throws PkiException if evaluation fails
*/
PolicyDecision evaluateRevocation(RevocationInputs inputs);
/**
* Retrieves a trace explaining a previous decision.
*
* @param decisionId decision id
* @return decision trace
* @throws IllegalArgumentException if {@code decisionId} is null
* @throws PkiException if trace retrieval fails
*/
PolicyTrace explain(PkiId decisionId);
}

91
pki/src/main/java/zeroecho/pki/api/ProfileService.java Normal file
View File

@@ -0,0 +1,91 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import java.util.List;
import zeroecho.pki.api.profile.CertificateProfile;
import zeroecho.pki.api.profile.ProfileQuery;
/**
* Profile registry for credential issuance.
*
* <p>
* Profiles define required/optional attributes, validity limits, and other
* constraints used by policy and framework mapping. Profiles are referenced by
* id during issuance.
* </p>
*/
public interface ProfileService {
/**
* Registers or updates a profile.
*
* @param profile profile definition
* @throws IllegalArgumentException if {@code profile} is null
* @throws PkiException if registration fails
*/
void register(CertificateProfile profile);
/**
* Retrieves a profile by id.
*
* @param profileId profile id
* @return profile
* @throws IllegalArgumentException if {@code profileId} is null/blank
* @throws PkiException if not found or retrieval fails
*/
CertificateProfile get(String profileId);
/**
* Lists profiles matching query constraints.
*
* @param query query constraints
* @return list of profiles
* @throws IllegalArgumentException if {@code query} is null
* @throws PkiException if listing fails
*/
List<CertificateProfile> list(ProfileQuery query);
/**
* Retires a profile to prevent further issuance.
*
* @param profileId profile id
* @param reason non-empty reason suitable for audit
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if retire fails
*/
void retire(String profileId, String reason);
}

99
pki/src/main/java/zeroecho/pki/api/PublicationService.java Normal file
View File

@@ -0,0 +1,99 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import java.util.List;
import zeroecho.pki.api.publication.PublicationQuery;
import zeroecho.pki.api.publication.PublicationRecord;
import zeroecho.pki.api.publication.PublicationResult;
import zeroecho.pki.api.publication.PublicationTarget;
/**
* Publication and distribution operations.
*
* <p>
* Publishing is an explicit operation enabling parity with established PKI
* systems. Implementations may publish credentials, CA materials, and status
* objects to configured targets such as filesystem mirrors, LDAP directories,
* HTTP endpoints, or object stores.
* </p>
*/
public interface PublicationService {
/**
* Publishes an issued credential to the specified target.
*
* @param credentialId credential id
* @param target publication target
* @return publication result
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if publication fails
*/
PublicationResult publishCredential(PkiId credentialId, PublicationTarget target);
/**
* Publishes CA materials (e.g., CA certificate sets) for the given CA entity to
* the specified target.
*
* @param caId CA entity id
* @param target publication target
* @return publication result
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if publication fails
*/
PublicationResult publishCaMaterials(PkiId caId, PublicationTarget target);
/**
* Publishes a status object to the specified target.
*
* @param statusObjectId status object id
* @param target publication target
* @return publication result
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if publication fails
*/
PublicationResult publishStatusObject(PkiId statusObjectId, PublicationTarget target);
/**
* Lists publication records matching query constraints.
*
* @param query publication query
* @return publication records
* @throws IllegalArgumentException if {@code query} is invalid
* @throws PkiException if listing fails
*/
List<PublicationRecord> listPublications(PublicationQuery query);
}

100
pki/src/main/java/zeroecho/pki/api/RevocationService.java Normal file
View File

@@ -0,0 +1,100 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import java.util.List;
import java.util.Optional;
import zeroecho.pki.api.revocation.HoldCommand;
import zeroecho.pki.api.revocation.RevocationQuery;
import zeroecho.pki.api.revocation.RevokeCommand;
import zeroecho.pki.api.revocation.RevokedRecord;
import zeroecho.pki.api.revocation.UnholdCommand;
/**
* Revocation operations and revocation record management.
*/
public interface RevocationService {
/**
* Revokes a credential.
*
* @param command revoke command
* @return revocation record
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if revocation fails
*/
RevokedRecord revoke(RevokeCommand command);
/**
* Places a credential on hold.
*
* @param command hold command
* @return revocation record
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if hold fails
*/
RevokedRecord hold(HoldCommand command);
/**
* Removes a hold from a credential.
*
* @param command unhold command
* @return revocation record
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if unhold fails
*/
RevokedRecord unhold(UnholdCommand command);
/**
* Retrieves revocation record for a credential.
*
* @param credentialId credential id
* @return record if present
* @throws IllegalArgumentException if {@code credentialId} is null
* @throws PkiException if retrieval fails
*/
Optional<RevokedRecord> get(PkiId credentialId);
/**
* Searches revocation records.
*
* @param query query constraints
* @return matching records
* @throws IllegalArgumentException if {@code query} is null
* @throws PkiException if search fails
*/
List<RevokedRecord> search(RevocationQuery query);
}

85
pki/src/main/java/zeroecho/pki/api/StatusObjectService.java Normal file
View File

@@ -0,0 +1,85 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import java.util.List;
import java.util.Optional;
import zeroecho.pki.api.status.StatusObject;
import zeroecho.pki.api.status.StatusObjectGenerateCommand;
import zeroecho.pki.api.status.StatusObjectQuery;
import zeroecho.pki.api.status.StatusObjectType;
/**
* Status object generation and retrieval.
*
* <p>
* Status objects include CRLs, delta CRLs, OCSP responses, or
* framework-specific revocation lists.
* </p>
*/
public interface StatusObjectService {
/**
* Generates a new status object for an issuer CA.
*
* @param command generation command
* @return generated status object
* @throws IllegalArgumentException if {@code command} is invalid
* @throws PkiException if generation fails
*/
StatusObject generate(StatusObjectGenerateCommand command);
/**
* Retrieves the latest status object of a given type for an issuer CA.
*
* @param issuerCaId issuer CA id
* @param type status object type
* @return latest status object if present
* @throws IllegalArgumentException if inputs are invalid
* @throws PkiException if retrieval fails
*/
Optional<StatusObject> getLatest(PkiId issuerCaId, StatusObjectType type);
/**
* Lists status objects matching query constraints.
*
* @param query query constraints
* @return matching status objects
* @throws IllegalArgumentException if {@code query} is invalid
* @throws PkiException if listing fails
*/
List<StatusObject> list(StatusObjectQuery query);
}

61
pki/src/main/java/zeroecho/pki/api/SubjectRef.java Normal file
View File

@@ -0,0 +1,61 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
/**
* Framework-agnostic subject identifier.
*
* <p>
* This identifier is used for policy evaluation, inventory queries, and audit
* correlation. Framework backends may map it to a distinguished name (DN), a
* claims subject, or a service identity, depending on the credential framework.
* </p>
*
* @param value non-empty subject reference
*/
public record SubjectRef(String value) {
/**
* Creates a subject reference.
*
* @param value non-empty subject reference
* @throws IllegalArgumentException if {@code value} is null or blank
*/
public SubjectRef {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("value must not be null/blank");
}
}
}

74
pki/src/main/java/zeroecho/pki/api/Validity.java Normal file
View File

@@ -0,0 +1,74 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api;
import java.time.Instant;
/**
* Validity interval for an issued credential.
*
* <p>
* The PKI core requires {@code notAfter} to be strictly after
* {@code notBefore}. Framework-specific interpretations (inclusive/exclusive)
* are resolved by the framework backend.
* </p>
*
* <p>
* Policy and profile constraints (maximum lifetime, not-before skew) must be
* enforced by the PKI runtime.
* </p>
*
* @param notBefore start of validity interval (inclusive)
* @param notAfter end of validity interval (must be after {@code notBefore})
*/
public record Validity(Instant notBefore, Instant notAfter) {
/**
* Creates a validity interval.
*
* @param notBefore start of validity interval (inclusive)
* @param notAfter end of validity interval
* @throws IllegalArgumentException if inputs are null or the interval is
* invalid
*/
public Validity {
if (notBefore == null || notAfter == null) {
throw new IllegalArgumentException("notBefore/notAfter must not be null");
}
if (!notAfter.isAfter(notBefore)) {
throw new IllegalArgumentException("notAfter must be after notBefore");
}
}
}

65
pki/src/main/java/zeroecho/pki/api/attr/AttributeAccessPolicy.java Normal file
View File

@@ -0,0 +1,65 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
import java.util.Set;
/**
* Governance hints controlling auditing and exportability of an attribute.
*
* <p>
* This model is intentionally minimal. Implementations may interpret it via a
* richer policy decision point (roles, purposes, tenants), but the presence of
* these hints allows consistent enforcement and auditing.
* </p>
*
* @param auditOnAllow if true, successful accesses should be audited
* @param auditOnDeny if true, denied accesses should be audited
* @param exportTargets allowed export targets
*/
public record AttributeAccessPolicy(boolean auditOnAllow, boolean auditOnDeny,
Set<AttributeExportTarget> exportTargets) {
/**
* Creates an access policy.
*
* @throws IllegalArgumentException if {@code exportTargets} is null
*/
public AttributeAccessPolicy {
if (exportTargets == null) {
throw new IllegalArgumentException("exportTargets must not be null");
}
}
}

66
pki/src/main/java/zeroecho/pki/api/attr/AttributeCatalogue.java Normal file
View File

@@ -0,0 +1,66 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
import java.util.List;
import java.util.Optional;
/**
* Registry/catalogue of attribute definitions.
*
* <p>
* The catalogue is the shared vocabulary across credential frameworks.
* Identifiers must never be reused with a different meaning. Definitions should
* be versioned under a controlled process.
* </p>
*/
public interface AttributeCatalogue {
/**
* Finds a definition by id.
*
* @param id attribute id
* @return definition if present
* @throws IllegalArgumentException if {@code id} is null
*/
Optional<AttributeDefinition> find(AttributeId id);
/**
* Lists all known definitions.
*
* @return list of definitions
*/
List<AttributeDefinition> listAll();
}

75
pki/src/main/java/zeroecho/pki/api/attr/AttributeDefinition.java Normal file
View File

@@ -0,0 +1,75 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
/**
* Typed and governed attribute definition used across credential frameworks.
*
* <p>
* The definition includes a stable identifier, type information, documentation
* metadata, and governance hints. Frameworks map universal attributes into
* framework-specific fields and extensions.
* </p>
*
* @param id stable attribute identifier
* @param displayName human-readable name
* @param valueType logical value type
* @param multiValued whether multiple values are allowed
* @param sensitivity sensitivity classification
* @param stability lifecycle maturity
* @param accessPolicy governance hints
* @param meta structured documentation metadata
*/
public record AttributeDefinition(AttributeId id, String displayName, AttributeValueType valueType, boolean multiValued,
AttributeSensitivity sensitivity, AttributeStability stability, AttributeAccessPolicy accessPolicy,
AttributeMeta meta) {
/**
* Creates an attribute definition.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public AttributeDefinition {
if (id == null) {
throw new IllegalArgumentException("id must not be null");
}
if (displayName == null || displayName.isBlank()) {
throw new IllegalArgumentException("displayName must not be null/blank");
}
if (valueType == null || sensitivity == null || stability == null || accessPolicy == null || meta == null) {
throw new IllegalArgumentException("non-null fields must not be null");
}
}
}

66
pki/src/main/java/zeroecho/pki/api/attr/AttributeExportTarget.java Normal file
View File

@@ -0,0 +1,66 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
/**
* Named export targets used by governance and publication pipelines.
*/
public enum AttributeExportTarget {
/**
* Export via a programmatic API.
*/
API,
/**
* Export for UI rendering.
*/
UI,
/**
* Export to LDAP directory.
*/
LDAP,
/**
* Export to backups.
*/
BACKUP,
/**
* Export to diagnostics/debugging channels (typically heavily redacted).
*/
DIAGNOSTICS
}

61
pki/src/main/java/zeroecho/pki/api/attr/AttributeId.java Normal file
View File

@@ -0,0 +1,61 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
/**
* Stable attribute identifier used by the attribute catalogue.
*
* <p>
* Identifiers should be globally stable (recommended as OIDs under a project or
* enterprise arc). Identifiers must never be reused with a different semantic
* meaning.
* </p>
*
* @param value non-empty identifier string
*/
public record AttributeId(String value) {
/**
* Creates an attribute identifier.
*
* @param value non-empty identifier string
* @throws IllegalArgumentException if {@code value} is null or blank
*/
public AttributeId {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("value must not be null/blank");
}
}
}

81
pki/src/main/java/zeroecho/pki/api/attr/AttributeMeta.java Normal file
View File

@@ -0,0 +1,81 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
import java.util.List;
import java.util.Map;
/**
* Structured, human-facing documentation metadata for an attribute definition.
*
* <p>
* This metadata is intended to be rendered in operator tooling, APIs, and UI.
* It must not contain secrets.
* </p>
*
* @param description normative description of meaning and usage
* @param notes additional guidance and security considerations
* @param examples example values (must not contain secrets)
* @param tags classification tags (e.g., "identity", "x509", "san")
* @param extra additional annotations for future extensions
* (non-sensitive)
*/
public record AttributeMeta(String description, List<String> notes, List<String> examples, List<String> tags,
Map<String, String> extra) {
/**
* Creates attribute metadata.
*
* @throws IllegalArgumentException if inputs are invalid or collections/maps
* are null
*/
public AttributeMeta {
if (description == null || description.isBlank()) {
throw new IllegalArgumentException("description must not be null/blank");
}
if (notes == null) {
throw new IllegalArgumentException("notes must not be null");
}
if (examples == null) {
throw new IllegalArgumentException("examples must not be null");
}
if (tags == null) {
throw new IllegalArgumentException("tags must not be null");
}
if (extra == null) {
throw new IllegalArgumentException("extra must not be null");
}
}
}

67
pki/src/main/java/zeroecho/pki/api/attr/AttributeSensitivity.java Normal file
View File

@@ -0,0 +1,67 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
/**
* Data sensitivity classification for an attribute.
*
* <p>
* Sensitivity influences default auditing/export/redaction behavior.
* Implementations must ensure that SECRET and SENSITIVE values are not exposed
* to logs or unauthorized channels.
* </p>
*/
public enum AttributeSensitivity {
/**
* Public value; can be disclosed broadly.
*/
PUBLIC,
/**
* Internal operational value; restricted to internal components and operators.
*/
INTERNAL,
/**
* Sensitive value; disclosure may create security or privacy risk.
*/
SENSITIVE,
/**
* Secret value; must not be disclosed outside the strictest trust boundary.
*/
SECRET
}

82
pki/src/main/java/zeroecho/pki/api/attr/AttributeSet.java Normal file
View File

@@ -0,0 +1,82 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
import java.util.List;
import java.util.Optional;
import java.util.Set;
/**
* Immutable set of typed attributes.
*
* <p>
* This is a passive container. Production code is expected to mediate
* read/write/export/derive operations through a governance/enforcement layer
* that performs ACL checks and emits audit events.
* </p>
*/
public interface AttributeSet {
/**
* Returns all attribute identifiers present in this set.
*
* @return set of attribute ids
*/
Set<AttributeId> ids();
/**
* Reads a single-valued attribute.
*
* <p>
* If the attribute is multi-valued, implementations may return empty or one
* chosen value; callers should prefer {@link #getAll(AttributeId)} when
* multi-valued is expected.
* </p>
*
* @param id attribute id
* @return attribute value if present
* @throws IllegalArgumentException if {@code id} is null
*/
Optional<AttributeValue> get(AttributeId id);
/**
* Reads a potentially multi-valued attribute.
*
* @param id attribute id
* @return list of values (empty if absent)
* @throws IllegalArgumentException if {@code id} is null
*/
List<AttributeValue> getAll(AttributeId id);
}

57
pki/src/main/java/zeroecho/pki/api/attr/AttributeStability.java Normal file
View File

@@ -0,0 +1,57 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
/**
* Lifecycle maturity of an attribute definition.
*/
public enum AttributeStability {
/**
* Attribute is stable and recommended for general use.
*/
STABLE,
/**
* Attribute is experimental and may change under a controlled evolution
* process.
*/
EXPERIMENTAL,
/**
* Attribute is deprecated and should not be used for new profiles.
*/
DEPRECATED
}

131
pki/src/main/java/zeroecho/pki/api/attr/AttributeValue.java Normal file
View File

@@ -0,0 +1,131 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
import java.time.Instant;
/**
* Typed attribute value.
*
* <p>
* Values are modeled as a sealed hierarchy for type safety and deterministic
* mapping. Implementations must treat values as potentially sensitive and apply
* redaction where required.
* </p>
*/
public sealed interface AttributeValue permits AttributeValue.StringValue, AttributeValue.BooleanValue,
AttributeValue.IntegerValue, AttributeValue.InstantValue, AttributeValue.BytesValue {
/**
* String value.
*
* @param value string content (may be empty depending on attribute definition)
*/
record StringValue(String value) implements AttributeValue {
/**
* Creates a string value.
*
* @param value string content
* @throws IllegalArgumentException if {@code value} is null
*/
public StringValue {
if (value == null) {
throw new IllegalArgumentException("value must not be null");
}
}
}
/**
* Boolean value.
*
* @param value boolean content
*/
record BooleanValue(boolean value) implements AttributeValue {
}
/**
* Integer/long value.
*
* @param value numeric content
*/
record IntegerValue(long value) implements AttributeValue {
}
/**
* Instant value.
*
* @param value timestamp content
*/
record InstantValue(Instant value) implements AttributeValue {
/**
* Creates an instant value.
*
* @param value timestamp
* @throws IllegalArgumentException if {@code value} is null
*/
public InstantValue {
if (value == null) {
throw new IllegalArgumentException("value must not be null");
}
}
}
/**
* Byte string value.
*
* <p>
* Byte values should be treated as potentially sensitive. Implementations must
* not log full contents.
* </p>
*
* @param value non-empty byte array
*/
record BytesValue(byte[] value) implements AttributeValue {
/**
* Creates a byte string value.
*
* @param value byte array (non-empty)
* @throws IllegalArgumentException if {@code value} is null or empty
*/
public BytesValue {
if (value == null || value.length == 0) {
throw new IllegalArgumentException("value must not be null/empty");
}
}
}
}

98
pki/src/main/java/zeroecho/pki/api/attr/AttributeValueType.java Normal file
View File

@@ -0,0 +1,98 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.attr;
/**
* Declares the logical value type of an attribute.
*
* <p>
* Framework backends map these logical types into framework-specific constructs
* (e.g., X.509 extensions, claims, or other credential fields).
* </p>
*/
public enum AttributeValueType {
/**
* UTF-8 string value.
*/
STRING,
/**
* Boolean value.
*/
BOOLEAN,
/**
* Integer/long value.
*/
INTEGER,
/**
* Timestamp value.
*/
INSTANT,
/**
* Raw byte string.
*/
BYTES,
/**
* Object identifier string.
*/
OID,
/**
* Distinguished Name representation (string form with normalization rules
* defined by profile/policy).
*/
DN,
/**
* GeneralName-like identity (DNS/IP/URI/email/etc.) represented in a canonical
* structured form.
*/
GENERAL_NAME,
/**
* Public key information representation (e.g., SPKI).
*/
KEY_INFO,
/**
* Structured composite value.
*/
STRUCT
}

62
pki/src/main/java/zeroecho/pki/api/attr/package-info.java Normal file
View File

@@ -0,0 +1,62 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
/**
* Attribute catalogue and attribute-level modeling.
*
* <p>
* This package defines a typed attribute system used across the PKI API and
* independent of any specific credential framework. Attributes are described
* through definitions and metadata and carried in structured containers to
* support safe reuse and deterministic mapping into concrete frameworks (e.g.,
* via a framework attribute mapper SPI).
* </p>
*
* <h2>Typical responsibilities</h2>
* <ul>
* <li>Define attribute identity and value types.</li>
* <li>Provide metadata needed for validation and governance (stability,
* sensitivity, etc.).</li>
* <li>Support export/import targets without binding to a certificate
* format.</li>
* </ul>
*
* <p>
* Access control and governance for attribute access is described in
* {@code zeroecho.pki.api.audit}.
* </p>
*
* @since 1.0
*/
package zeroecho.pki.api.attr;

61
pki/src/main/java/zeroecho/pki/api/audit/AccessAction.java Normal file
View File

@@ -0,0 +1,61 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.audit;
/**
* Action performed on an attribute for access governance.
*/
public enum AccessAction {
/**
* Read an attribute value.
*/
READ,
/**
* Write or modify an attribute value.
*/
WRITE,
/**
* Export attribute value to an external channel (e.g., UI, LDAP, backups).
*/
EXPORT,
/**
* Derive/computed attribute value from other sources.
*/
DERIVE
}

74
pki/src/main/java/zeroecho/pki/api/audit/AccessContext.java Normal file
View File

@@ -0,0 +1,74 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.audit;
import java.util.Optional;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.PkiId;
/**
* Context used for attribute ACL checks and audit correlation.
*
* @param principal actor requesting access
* @param purpose declared purpose of access
* @param objectId optional object id being accessed (credential id, request
* id, etc.)
* @param formatId optional format id relevant to the object being accessed
*/
public record AccessContext(Principal principal, Purpose purpose, Optional<PkiId> objectId,
Optional<FormatId> formatId) {
/**
* Creates an access context.
*
* @throws IllegalArgumentException if mandatory inputs are null or optional
* containers are null
*/
public AccessContext {
if (principal == null) {
throw new IllegalArgumentException("principal must not be null");
}
if (purpose == null) {
throw new IllegalArgumentException("purpose must not be null");
}
if (objectId == null) {
throw new IllegalArgumentException("objectId must not be null");
}
if (formatId == null) {
throw new IllegalArgumentException("formatId must not be null");
}
}
}

51
pki/src/main/java/zeroecho/pki/api/audit/AccessDecision.java Normal file
View File

@@ -0,0 +1,51 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.audit;
/**
* Decision outcome of an access control check.
*/
public enum AccessDecision {
/**
* Access is allowed.
*/
ALLOW,
/**
* Access is denied.
*/
DENY
}

61
pki/src/main/java/zeroecho/pki/api/audit/AttributeAccessController.java Normal file
View File

@@ -0,0 +1,61 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.audit;
import zeroecho.pki.api.attr.AttributeDefinition;
/**
* Policy decision point for attribute-level access control.
*
* <p>
* This interface decides whether an attribute action is permitted given the
* attribute definition and the access context. A separate enforcement layer is
* expected to record audit events.
* </p>
*/
@FunctionalInterface
public interface AttributeAccessController {
/**
* Evaluates an access request.
*
* @param definition attribute definition
* @param action access action
* @param context access context
* @return allow/deny decision
* @throws IllegalArgumentException if inputs are null
*/
AccessDecision decide(AttributeDefinition definition, AccessAction action, AccessContext context);
}

118
pki/src/main/java/zeroecho/pki/api/audit/AttributeGovernanceService.java Normal file
View File

@@ -0,0 +1,118 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.audit;
import java.util.Optional;
import zeroecho.pki.api.attr.AttributeCatalogue;
import zeroecho.pki.api.attr.AttributeId;
import zeroecho.pki.api.attr.AttributeSet;
import zeroecho.pki.api.attr.AttributeValue;
/**
* Policy enforcement point for attribute access with mandatory auditing.
*
* <p>
* All attribute read/write/export/derive operations should be performed through
* this service to ensure: (1) consistent ACL evaluation and (2) consistent
* audit event emission.
* </p>
*/
public interface AttributeGovernanceService {
/**
* Reads an attribute value after applying access control.
*
* @param catalogue attribute catalogue used to resolve definitions
* @param set attribute set being accessed
* @param id attribute id
* @param context access context
* @return value if present and access is allowed; empty otherwise
* @throws IllegalArgumentException if inputs are null
*/
Optional<AttributeValue> read(AttributeCatalogue catalogue, AttributeSet set, AttributeId id,
AccessContext context);
/**
* Writes an attribute value after applying access control.
*
* @param catalogue attribute catalogue used to resolve definitions
* @param set attribute set being modified
* @param id attribute id
* @param value value to write
* @param context access context
* @return new attribute set instance containing the updated value
* @throws IllegalArgumentException if inputs are null
*/
AttributeSet write(AttributeCatalogue catalogue, AttributeSet set, AttributeId id, AttributeValue value,
AccessContext context);
/**
* Exports an attribute value after applying access control.
*
* <p>
* Export may imply redaction. The exact redaction rules are
* implementation-defined and should take attribute sensitivity and export
* target into account.
* </p>
*
* @param catalogue attribute catalogue used to resolve definitions
* @param set attribute set being exported from
* @param id attribute id
* @param context access context
* @return exported value if present and allowed; empty otherwise
* @throws IllegalArgumentException if inputs are null
*/
Optional<AttributeValue> export(AttributeCatalogue catalogue, AttributeSet set, AttributeId id,
AccessContext context);
/**
* Derives an attribute value from other inputs after applying access control.
*
* <p>
* Derivation may be used to compute attributes such as fingerprints or
* normalized identity fields.
* </p>
*
* @param catalogue attribute catalogue used to resolve definitions
* @param set attribute set being modified
* @param id attribute id
* @param context access context
* @return new attribute set instance containing the derived value
* (implementation-defined)
* @throws IllegalArgumentException if inputs are null
*/
AttributeSet derive(AttributeCatalogue catalogue, AttributeSet set, AttributeId id, AccessContext context);
}

99
pki/src/main/java/zeroecho/pki/api/audit/AuditEvent.java Normal file
View File

@@ -0,0 +1,99 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.audit;
import java.time.Instant;
import java.util.Map;
import java.util.Optional;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.PkiId;
/**
* Auditable event emitted by the PKI core.
*
* <p>
* Audit events may represent high-level PKI operations (issuance, revocation,
* publication, backup) and attribute access governance outcomes.
* Implementations must ensure no secrets appear in {@code details}.
* </p>
*
* @param time event time (server time)
* @param category non-empty category (e.g., "ISSUANCE", "REVOCATION",
* "ATTRIBUTE_ACCESS")
* @param action non-empty action string (e.g., "ISSUE_END_ENTITY", "REVOKE",
* "READ")
* @param principal actor responsible for the event
* @param purpose purpose of the operation/access
* @param objectId optional subject object id (credential id, request id, etc.)
* @param formatId optional format id related to the object
* @param details additional non-sensitive key/value details
*/
public record AuditEvent(Instant time, String category, String action, Principal principal, Purpose purpose,
Optional<PkiId> objectId, Optional<FormatId> formatId, Map<String, String> details) {
/**
* Creates an audit event.
*
* @throws IllegalArgumentException if inputs are invalid or optional
* containers/maps are null
*/
public AuditEvent {
if (time == null) {
throw new IllegalArgumentException("time must not be null");
}
if (category == null || category.isBlank()) {
throw new IllegalArgumentException("category must not be null/blank");
}
if (action == null || action.isBlank()) {
throw new IllegalArgumentException("action must not be null/blank");
}
if (principal == null) {
throw new IllegalArgumentException("principal must not be null");
}
if (purpose == null) {
throw new IllegalArgumentException("purpose must not be null");
}
if (objectId == null) {
throw new IllegalArgumentException("objectId must not be null");
}
if (formatId == null) {
throw new IllegalArgumentException("formatId must not be null");
}
if (details == null) {
throw new IllegalArgumentException("details must not be null");
}
}
}

66
pki/src/main/java/zeroecho/pki/api/audit/AuditQuery.java Normal file
View File

@@ -0,0 +1,66 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.audit;
import java.time.Instant;
import java.util.Optional;
import zeroecho.pki.api.PkiId;
/**
* Query constraints for searching audit events.
*
* @param category optional category filter
* @param action optional action filter
* @param after optional lower bound for event time
* @param before optional upper bound for event time
* @param objectId optional object id filter
* @param principalName optional principal name filter
*/
public record AuditQuery(Optional<String> category, Optional<String> action, Optional<Instant> after,
Optional<Instant> before, Optional<PkiId> objectId, Optional<String> principalName) {
/**
* Creates an audit query.
*
* @throws IllegalArgumentException if any optional container is null
*/
public AuditQuery {
if (category == null || action == null || after == null || before == null || objectId == null
|| principalName == null) {
throw new IllegalArgumentException("optional fields must not be null");
}
}
}

80
pki/src/main/java/zeroecho/pki/api/audit/AuditService.java Normal file
View File

@@ -0,0 +1,80 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.audit;
import java.util.List;
import java.util.Optional;
import zeroecho.pki.api.PkiId;
/**
* Records and queries audit events for PKI operations and attribute governance.
*
* <p>
* Implementations must ensure sensitive data is never stored or logged in clear
* text.
* </p>
*/
public interface AuditService {
/**
* Records an audit event.
*
* @param event audit event
* @throws IllegalArgumentException if {@code event} is null
* @throws RuntimeException if recording fails (implementation-defined)
*/
void record(AuditEvent event);
/**
* Searches audit events by query constraints.
*
* @param query query constraints
* @return matching audit events
* @throws IllegalArgumentException if {@code query} is null
* @throws RuntimeException if search fails
*/
List<AuditEvent> search(AuditQuery query);
/**
* Retrieves an audit event by id if the implementation assigns stable ids.
*
* @param eventId event id
* @return audit event if present
* @throws IllegalArgumentException if {@code eventId} is null
* @throws RuntimeException if retrieval fails
*/
Optional<AuditEvent> get(PkiId eventId);
}

63
pki/src/main/java/zeroecho/pki/api/audit/Principal.java Normal file
View File

@@ -0,0 +1,63 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.audit;
/**
* Identifies an actor performing an operation or requesting access.
*
* <p>
* A principal may represent a human user, service account, subsystem component,
* or a scheduled job.
* </p>
*
* @param type principal type (e.g., "USER", "SERVICE", "COMPONENT")
* @param name principal name/identifier
*/
public record Principal(String type, String name) {
/**
* Creates a principal.
*
* @throws IllegalArgumentException if inputs are null/blank
*/
public Principal {
if (type == null || type.isBlank()) {
throw new IllegalArgumentException("type must not be null/blank");
}
if (name == null || name.isBlank()) {
throw new IllegalArgumentException("name must not be null/blank");
}
}
}

59
pki/src/main/java/zeroecho/pki/api/audit/Purpose.java Normal file
View File

@@ -0,0 +1,59 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.audit;
/**
* Declares the purpose of an operation/access for governance and auditing.
*
* <p>
* Examples: {@code ISSUANCE}, {@code VALIDATION}, {@code UI_RENDER},
* {@code BACKUP_EXPORT}, {@code LDAP_PUBLISH}.
* </p>
*
* @param value non-empty purpose string
*/
public record Purpose(String value) {
/**
* Creates a purpose.
*
* @throws IllegalArgumentException if {@code value} is null/blank
*/
public Purpose {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("value must not be null/blank");
}
}
}

59
pki/src/main/java/zeroecho/pki/api/audit/package-info.java Normal file
View File

@@ -0,0 +1,59 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
/**
* Audit and governance API.
*
* <p>
* This package defines audit events, principals, purposes, queries, and
* attribute-access governance abstractions used to support compliance and
* operational forensics.
* </p>
*
* <h2>Security</h2>
* <ul>
* <li>Audit events MUST NOT contain private keys, shared secrets, or plaintext
* sensitive content.</li>
* <li>Audit records should be structured and stable for long-term retention and
* analysis.</li>
* </ul>
*
* <p>
* The persistence and routing of audit events is an SPI concern (e.g.,
* {@code zeroecho.pki.spi.AuditSink}).
* </p>
*
* @since 1.0
*/
package zeroecho.pki.api.audit;

69
pki/src/main/java/zeroecho/pki/api/backup/BackupArtifact.java Normal file
View File

@@ -0,0 +1,69 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.backup;
import zeroecho.pki.api.BackupService;
import zeroecho.pki.api.EncodedObject;
import zeroecho.pki.api.Encoding;
import zeroecho.pki.api.PkiId;
/**
* Opaque backup artifact produced by {@link BackupService}.
*
* <p>
* The payload is typically {@link Encoding#BINARY}. The internal structure is
* implementation-defined (e.g., tar/zip-like). Consumers should treat it as
* opaque.
* </p>
*
* @param backupId backup identifier
* @param payload backup payload bytes
*/
public record BackupArtifact(PkiId backupId, EncodedObject payload) {
/**
* Creates a backup artifact.
*
* @throws IllegalArgumentException if inputs are null
*/
public BackupArtifact {
if (backupId == null) {
throw new IllegalArgumentException("backupId must not be null");
}
if (payload == null) {
throw new IllegalArgumentException("payload must not be null");
}
}
}

68
pki/src/main/java/zeroecho/pki/api/backup/BackupRequest.java Normal file
View File

@@ -0,0 +1,68 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.backup;
import zeroecho.pki.api.KeyRef;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Requests creation of a PKI backup.
*
* <p>
* Backups are expected to contain PKI state (CAs, credentials, requests,
* revocations, profiles, publication records, policy traces). Private keys are
* excluded and referenced via {@link KeyRef}.
* </p>
*
* @param label operator-provided label for human identification
* @param attributes optional backup metadata (may be empty but not null)
*/
public record BackupRequest(String label, AttributeSet attributes) {
/**
* Creates a backup request.
*
* @throws IllegalArgumentException if {@code label} is null/blank or
* {@code attributes} is null
*/
public BackupRequest {
if (label == null || label.isBlank()) {
throw new IllegalArgumentException("label must not be null/blank");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

58
pki/src/main/java/zeroecho/pki/api/backup/BackupVerificationReport.java Normal file
View File

@@ -0,0 +1,58 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.backup;
import java.util.List;
/**
* Verification results for a backup artifact.
*
* @param valid true if the artifact is structurally valid and integrity checks
* passed
* @param issues list of issues found (non-sensitive)
*/
public record BackupVerificationReport(boolean valid, List<String> issues) {
/**
* Creates a backup verification report.
*
* @throws IllegalArgumentException if {@code issues} is null
*/
public BackupVerificationReport {
if (issues == null) {
throw new IllegalArgumentException("issues must not be null");
}
}
}

68
pki/src/main/java/zeroecho/pki/api/backup/RestoreReport.java Normal file
View File

@@ -0,0 +1,68 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.backup;
import java.util.List;
import zeroecho.pki.api.PkiId;
/**
* Result report for a restore operation.
*
* @param restoreId restore identifier
* @param success true if restore completed successfully
* @param warnings operator-readable warnings (non-sensitive)
* @param errors operator-readable errors (non-sensitive)
*/
public record RestoreReport(PkiId restoreId, boolean success, List<String> warnings, List<String> errors) {
/**
* Creates a restore report.
*
* @throws IllegalArgumentException if {@code restoreId} is null or lists are
* null
*/
public RestoreReport {
if (restoreId == null) {
throw new IllegalArgumentException("restoreId must not be null");
}
if (warnings == null) {
throw new IllegalArgumentException("warnings must not be null");
}
if (errors == null) {
throw new IllegalArgumentException("errors must not be null");
}
}
}

60
pki/src/main/java/zeroecho/pki/api/backup/RestoreRequest.java Normal file
View File

@@ -0,0 +1,60 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.backup;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Requests restore of PKI state from a backup artifact.
*
* @param artifact backup artifact
* @param attributes optional restore hints (may be empty but not null)
*/
public record RestoreRequest(BackupArtifact artifact, AttributeSet attributes) {
/**
* Creates a restore request.
*
* @throws IllegalArgumentException if inputs are null
*/
public RestoreRequest {
if (artifact == null) {
throw new IllegalArgumentException("artifact must not be null");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

61
pki/src/main/java/zeroecho/pki/api/backup/package-info.java Normal file
View File

@@ -0,0 +1,61 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
/**
* Backup and restore domain model.
*
* <p>
* This package provides request/response and artifact model types used for
* backing up and restoring PKI state. The intent is to support offline escrow,
* migration, disaster recovery, and integrity verification workflows.
* </p>
*
* <h2>Scope</h2>
* <ul>
* <li>Backup artifacts describe exported PKI state suitable for durable
* storage.</li>
* <li>Verification reports provide evidence that backups are structurally valid
* and complete.</li>
* <li>Restore requests and reports model controlled restoration
* operations.</li>
* </ul>
*
* <p>
* Concrete serialization formats and transport mechanisms are handled by
* services and the transfer layer.
* </p>
*
* @since 1.0
*/
package zeroecho.pki.api.backup;

86
pki/src/main/java/zeroecho/pki/api/ca/CaCreateCommand.java Normal file
View File

@@ -0,0 +1,86 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.ca;
import java.util.Optional;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.KeyRef;
import zeroecho.pki.api.SubjectRef;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Command to create a new root CA entity and issue its initial CA credential.
*
* <p>
* If {@code keyRef} is absent, the runtime may generate a new key pair
* depending on policy and runtime wiring. This command carries universal
* {@code attributes} used by policy and mapping.
* </p>
*
* @param formatId target credential format
* @param subjectRef normalized CA subject reference
* @param profileId profile id governing issuance and mapping
* @param keyRef optional existing key reference; empty requests key
* generation
* @param attributes universal attributes (may be empty but not null)
*/
public record CaCreateCommand(FormatId formatId, SubjectRef subjectRef, String profileId, Optional<KeyRef> keyRef,
AttributeSet attributes) {
/**
* Creates a CA create command.
*
* @throws IllegalArgumentException if inputs are invalid or optional container
* is null
*/
public CaCreateCommand {
if (formatId == null) {
throw new IllegalArgumentException("formatId must not be null");
}
if (subjectRef == null) {
throw new IllegalArgumentException("subjectRef must not be null");
}
if (profileId == null || profileId.isBlank()) {
throw new IllegalArgumentException("profileId must not be null/blank");
}
if (keyRef == null) {
throw new IllegalArgumentException("keyRef must not be null");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

86
pki/src/main/java/zeroecho/pki/api/ca/CaImportCommand.java Normal file
View File

@@ -0,0 +1,86 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.ca;
import zeroecho.pki.api.EncodedObject;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.KeyRef;
import zeroecho.pki.api.SubjectRef;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Command to import an existing root CA credential into PKI inventory.
*
* <p>
* This operation registers a CA entity and associates it with an externally
* managed key reference.
* </p>
*
* @param formatId credential format id
* @param subjectRef normalized CA subject reference
* @param profileId profile id for mapping/constraints
* @param keyRef reference to private key material
* @param existingCaCredential existing CA credential payload (certificate-like)
* @param attributes universal attributes (may be empty but not null)
*/
public record CaImportCommand(FormatId formatId, SubjectRef subjectRef, String profileId, KeyRef keyRef,
EncodedObject existingCaCredential, AttributeSet attributes) {
/**
* Creates a CA import command.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public CaImportCommand {
if (formatId == null) {
throw new IllegalArgumentException("formatId must not be null");
}
if (subjectRef == null) {
throw new IllegalArgumentException("subjectRef must not be null");
}
if (profileId == null || profileId.isBlank()) {
throw new IllegalArgumentException("profileId must not be null/blank");
}
if (keyRef == null) {
throw new IllegalArgumentException("keyRef must not be null");
}
if (existingCaCredential == null) {
throw new IllegalArgumentException("existingCaCredential must not be null");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

83
pki/src/main/java/zeroecho/pki/api/ca/CaKeyRotationCommand.java Normal file
View File

@@ -0,0 +1,83 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.ca;
import java.util.Optional;
import zeroecho.pki.api.KeyRef;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Command to rotate a CA key reference and issue new corresponding CA
* credentials.
*
* <p>
* Key rotation changes the underlying key material. Historical key references
* and credentials must remain discoverable for audit and validation of
* previously issued credentials.
* </p>
*
* @param caId CA entity id
* @param newKeyRef optional new key reference; empty requests key generation
* via runtime wiring
* @param issuerCaId optional issuer CA id (required for intermediate rotation;
* empty for root depending on policy)
* @param attributes universal attributes (may be empty but not null)
*/
public record CaKeyRotationCommand(PkiId caId, Optional<KeyRef> newKeyRef, Optional<PkiId> issuerCaId,
AttributeSet attributes) {
/**
* Creates a CA key rotation command.
*
* @throws IllegalArgumentException if inputs are invalid or optional containers
* are null
*/
public CaKeyRotationCommand {
if (caId == null) {
throw new IllegalArgumentException("caId must not be null");
}
if (newKeyRef == null) {
throw new IllegalArgumentException("newKeyRef must not be null");
}
if (issuerCaId == null) {
throw new IllegalArgumentException("issuerCaId must not be null");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

51
pki/src/main/java/zeroecho/pki/api/ca/CaKind.java Normal file
View File

@@ -0,0 +1,51 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.ca;
/**
* Classifies CA entity type.
*/
public enum CaKind {
/**
* Root CA (initial credential is typically self-issued).
*/
ROOT,
/**
* Intermediate CA (issued by another CA).
*/
INTERMEDIATE
}

64
pki/src/main/java/zeroecho/pki/api/ca/CaQuery.java Normal file
View File

@@ -0,0 +1,64 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.ca;
import java.util.Optional;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.SubjectRef;
/**
* Query constraints for listing CA entities.
*
* @param kind optional CA kind filter
* @param state optional state filter
* @param formatId optional framework filter (implementation-defined; may map
* to CA credential format)
* @param subjectRef optional subject filter
*/
public record CaQuery(Optional<CaKind> kind, Optional<CaState> state, Optional<FormatId> formatId,
Optional<SubjectRef> subjectRef) {
/**
* Creates a CA query.
*
* @throws IllegalArgumentException if any optional container is null
*/
public CaQuery {
if (kind == null || state == null || formatId == null || subjectRef == null) {
throw new IllegalArgumentException("optional fields must not be null");
}
}
}

93
pki/src/main/java/zeroecho/pki/api/ca/CaRecord.java Normal file
View File

@@ -0,0 +1,93 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.ca;
import java.util.List;
import zeroecho.pki.api.KeyRef;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.SubjectRef;
import zeroecho.pki.api.credential.Credential;
/**
* Represents a CA entity and its issued CA credentials.
*
* <p>
* A CA entity may have multiple CA credentials to support:
* </p>
* <ul>
* <li>cross-signing (multiple issuers for the same subject key),</li>
* <li>credential rollover (new CA credential with the same key),</li>
* <li>key rotation (new CA key with a new set of credentials).</li>
* </ul>
*
* @param caId CA identifier
* @param kind CA kind (root or intermediate)
* @param state operational state
* @param issuerKeyRef key reference used for issuing operations (private key
* reference)
* @param subjectRef normalized subject reference
* @param caCredentials CA credentials currently associated with the entity
* (historical and active)
*/
public record CaRecord(PkiId caId, CaKind kind, CaState state, KeyRef issuerKeyRef, SubjectRef subjectRef,
List<Credential> caCredentials) {
/**
* Creates a CA record.
*
* @throws IllegalArgumentException if inputs are null
*/
public CaRecord {
if (caId == null) {
throw new IllegalArgumentException("caId must not be null");
}
if (kind == null) {
throw new IllegalArgumentException("kind must not be null");
}
if (state == null) {
throw new IllegalArgumentException("state must not be null");
}
if (issuerKeyRef == null) {
throw new IllegalArgumentException("issuerKeyRef must not be null");
}
if (subjectRef == null) {
throw new IllegalArgumentException("subjectRef must not be null");
}
if (caCredentials == null) {
throw new IllegalArgumentException("caCredentials must not be null");
}
}
}

81
pki/src/main/java/zeroecho/pki/api/ca/CaRolloverCommand.java Normal file
View File

@@ -0,0 +1,81 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.ca;
import java.util.Optional;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.Validity;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Command to roll over a CA credential while keeping the same key reference.
*
* <p>
* Rollover issues a new CA credential for the CA entity without changing the
* underlying key material. Historical credentials remain accessible for audit
* and chain selection.
* </p>
*
* @param caId CA entity id
* @param issuerCaId optional issuer CA id (empty for self-issued root
* rollover where applicable)
* @param requestedValidity optional requested validity
* @param attributes universal attributes (may be empty but not null)
*/
public record CaRolloverCommand(PkiId caId, Optional<PkiId> issuerCaId, Optional<Validity> requestedValidity,
AttributeSet attributes) {
/**
* Creates a CA rollover command.
*
* @throws IllegalArgumentException if inputs are invalid or optional containers
* are null
*/
public CaRolloverCommand {
if (caId == null) {
throw new IllegalArgumentException("caId must not be null");
}
if (issuerCaId == null) {
throw new IllegalArgumentException("issuerCaId must not be null");
}
if (requestedValidity == null) {
throw new IllegalArgumentException("requestedValidity must not be null");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

75
pki/src/main/java/zeroecho/pki/api/ca/CaState.java Normal file
View File

@@ -0,0 +1,75 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.ca;
/**
* Operational state of a CA entity.
*/
public enum CaState {
/**
* CA is active and may issue new credentials according to policy.
*/
ACTIVE,
/**
* CA is retired and must not issue new credentials.
*
* <p>
* Historical credentials remain available for validation and audit until they
* expire or are revoked.
* </p>
*/
RETIRED,
/**
* CA is compromised and must not be used for issuance.
*
* <p>
* Operators should perform incident response, publish updated status objects,
* and rotate trust anchors.
* </p>
*/
COMPROMISED,
/**
* CA is administratively disabled.
*
* <p>
* This state is distinct from retirement and may be reversible.
* </p>
*/
DISABLED
}

90
pki/src/main/java/zeroecho/pki/api/ca/IntermediateCertIssueCommand.java Normal file
View File

@@ -0,0 +1,90 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.ca;
import java.util.Optional;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.Validity;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Command to issue a new CA credential for an existing intermediate CA entity.
*
* <p>
* This command supports cross-signing (issuing with a different issuer CA) and
* renewal scenarios.
* </p>
*
* @param formatId credential format id
* @param issuerCaId issuer CA entity id
* @param subjectCaId subject CA entity id (the intermediate being
* certified)
* @param profileId profile id governing issuance
* @param requestedValidity optional requested validity (policy may
* override/deny)
* @param attributes universal attributes (may be empty but not null)
*/
public record IntermediateCertIssueCommand(FormatId formatId, PkiId issuerCaId, PkiId subjectCaId, String profileId,
Optional<Validity> requestedValidity, AttributeSet attributes) {
/**
* Creates an intermediate CA credential issuance command.
*
* @throws IllegalArgumentException if inputs are invalid or optional container
* is null
*/
public IntermediateCertIssueCommand {
if (formatId == null) {
throw new IllegalArgumentException("formatId must not be null");
}
if (issuerCaId == null) {
throw new IllegalArgumentException("issuerCaId must not be null");
}
if (subjectCaId == null) {
throw new IllegalArgumentException("subjectCaId must not be null");
}
if (profileId == null || profileId.isBlank()) {
throw new IllegalArgumentException("profileId must not be null/blank");
}
if (requestedValidity == null) {
throw new IllegalArgumentException("requestedValidity must not be null");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

86
pki/src/main/java/zeroecho/pki/api/ca/IntermediateCreateCommand.java Normal file
View File

@@ -0,0 +1,86 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.ca;
import java.util.Optional;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.KeyRef;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.SubjectRef;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Command to create a new intermediate CA entity and issue its initial CA
* credential.
*
* @param formatId credential format id
* @param issuerCaId issuer CA entity id
* @param subjectRef normalized subject reference for the intermediate
* @param profileId profile id governing issuance
* @param keyRef optional existing key reference; empty requests key
* generation
* @param attributes universal attributes (may be empty but not null)
*/
public record IntermediateCreateCommand(FormatId formatId, PkiId issuerCaId, SubjectRef subjectRef, String profileId,
Optional<KeyRef> keyRef, AttributeSet attributes) {
/**
* Creates an intermediate create command.
*
* @throws IllegalArgumentException if inputs are invalid or optional container
* is null
*/
public IntermediateCreateCommand {
if (formatId == null) {
throw new IllegalArgumentException("formatId must not be null");
}
if (issuerCaId == null) {
throw new IllegalArgumentException("issuerCaId must not be null");
}
if (subjectRef == null) {
throw new IllegalArgumentException("subjectRef must not be null");
}
if (profileId == null || profileId.isBlank()) {
throw new IllegalArgumentException("profileId must not be null/blank");
}
if (keyRef == null) {
throw new IllegalArgumentException("keyRef must not be null");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

60
pki/src/main/java/zeroecho/pki/api/ca/package-info.java Normal file
View File

@@ -0,0 +1,60 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
/**
* Certificate Authority (CA) domain model.
*
* <p>
* This package contains CA records, lifecycle state, CA kinds, and CA-related
* commands and queries. It models root and intermediate CA management,
* including creation, import, rollover, and key rotation operations.
* </p>
*
* <h2>Responsibilities</h2>
* <ul>
* <li>Represent CA identity and state through records and enums.</li>
* <li>Define CA management commands used by
* {@link zeroecho.pki.api.CaService}.</li>
* <li>Support intermediate CA creation and intermediate certificate
* issuance.</li>
* </ul>
*
* <p>
* Concrete certificate framework specifics are delegated to framework
* integrations.
* </p>
*
* @since 1.0
*/
package zeroecho.pki.api.ca;

117
pki/src/main/java/zeroecho/pki/api/credential/Credential.java Normal file
View File

@@ -0,0 +1,117 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.credential;
import zeroecho.pki.api.EncodedObject;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.IssuerRef;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.SubjectRef;
import zeroecho.pki.api.Validity;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Issued credential with mandatory core metadata and universal attributes.
*
* <p>
* The PKI core does not assume X.509 semantics. The {@code serialOrUniqueId}
* field maps to X.509 serial numbers when applicable, but can represent another
* framework's unique identifier.
* </p>
*
* <p>
* The {@code publicKeyId} is intended to group multiple credentials for the
* same key (e.g., cross-signing, migrations, or parallel classical/PQC chains).
* </p>
*
* @param credentialId stable identifier for the credential (typically a
* fingerprint of encoded bytes)
* @param formatId framework identifier
* @param issuerRef issuing CA reference
* @param subjectRef normalized subject reference
* @param validity validity interval
* @param serialOrUniqueId framework-specific unique identifier (serial for
* X.509)
* @param publicKeyId stable identifier derived from the subject public key
* @param profileId profile governing issuance
* @param status inventory status
* @param encoded encoded credential bytes
* @param attributes universal attribute set
*/
public record Credential(PkiId credentialId, FormatId formatId, IssuerRef issuerRef, SubjectRef subjectRef,
Validity validity, String serialOrUniqueId, PkiId publicKeyId, String profileId, CredentialStatus status,
EncodedObject encoded, AttributeSet attributes) {
/**
* Creates a credential record.
*
* @throws IllegalArgumentException if mandatory inputs are invalid
*/
public Credential {
if (credentialId == null) {
throw new IllegalArgumentException("credentialId must not be null");
}
if (formatId == null) {
throw new IllegalArgumentException("formatId must not be null");
}
if (issuerRef == null) {
throw new IllegalArgumentException("issuerRef must not be null");
}
if (subjectRef == null) {
throw new IllegalArgumentException("subjectRef must not be null");
}
if (validity == null) {
throw new IllegalArgumentException("validity must not be null");
}
if (serialOrUniqueId == null || serialOrUniqueId.isBlank()) {
throw new IllegalArgumentException("serialOrUniqueId must not be null/blank");
}
if (publicKeyId == null) {
throw new IllegalArgumentException("publicKeyId must not be null");
}
if (profileId == null || profileId.isBlank()) {
throw new IllegalArgumentException("profileId must not be null/blank");
}
if (status == null) {
throw new IllegalArgumentException("status must not be null");
}
if (encoded == null) {
throw new IllegalArgumentException("encoded must not be null");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

70
pki/src/main/java/zeroecho/pki/api/credential/CredentialBundle.java Normal file
View File

@@ -0,0 +1,70 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.credential;
import java.util.List;
import zeroecho.pki.api.EncodedObject;
/**
* Bundle of a primary credential and supporting objects.
*
* <p>
* Supporting objects enable distribution and validation. For X.509 these are
* typically chain certificates. Frameworks may define additional supporting
* artifacts.
* </p>
*
* @param credential primary credential
* @param supportingObjects supporting artifacts (framework-defined ordering)
*/
public record CredentialBundle(Credential credential, List<EncodedObject> supportingObjects) {
/**
* Creates a bundle.
*
* @param credential primary credential
* @param supportingObjects supporting artifacts (non-null, may be empty)
* @throws IllegalArgumentException if inputs are null
*/
public CredentialBundle {
if (credential == null) {
throw new IllegalArgumentException("credential must not be null");
}
if (supportingObjects == null) {
throw new IllegalArgumentException("supportingObjects must not be null");
}
}
}

70
pki/src/main/java/zeroecho/pki/api/credential/CredentialQuery.java Normal file
View File

@@ -0,0 +1,70 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.credential;
import java.time.Instant;
import java.util.Optional;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.SubjectRef;
/**
* Query constraints for searching credentials in inventory.
*
* @param formatId optional framework filter
* @param issuerCaId optional issuer CA filter
* @param subjectRef optional subject filter
* @param profileId optional profile filter
* @param status optional status filter
* @param publicKeyId optional public key grouping filter
* @param validAt optional evaluation time for validity-based filtering
*/
public record CredentialQuery(Optional<FormatId> formatId, Optional<PkiId> issuerCaId, Optional<SubjectRef> subjectRef,
Optional<String> profileId, Optional<CredentialStatus> status, Optional<PkiId> publicKeyId,
Optional<Instant> validAt) {
/**
* Creates a credential query.
*
* @throws IllegalArgumentException if any optional container is null
*/
public CredentialQuery {
if (formatId == null || issuerCaId == null || subjectRef == null || profileId == null || status == null
|| publicKeyId == null || validAt == null) {
throw new IllegalArgumentException("optional fields must not be null");
}
}
}

61
pki/src/main/java/zeroecho/pki/api/credential/CredentialStatus.java Normal file
View File

@@ -0,0 +1,61 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.credential;
/**
* Status of a credential as tracked by PKI inventory.
*
* <p>
* Status may be computed from validity and revocation state or stored directly
* depending on implementation.
* </p>
*/
public enum CredentialStatus {
/**
* Credential is issued and not revoked. Validity may still expire later.
*/
ISSUED,
/**
* Credential is revoked.
*/
REVOKED,
/**
* Credential validity interval has ended.
*/
EXPIRED
}

53
pki/src/main/java/zeroecho/pki/api/credential/package-info.java Normal file
View File

@@ -0,0 +1,53 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
/**
* Credential inventory domain model.
*
* <p>
* This package defines the model types representing issued credentials and
* their inventory view, including status tracking and query objects. It is used
* by {@link zeroecho.pki.api.CredentialInventoryService}.
* </p>
*
* <h2>Notes</h2>
* <ul>
* <li>Credentials are treated as immutable artifacts once issued.</li>
* <li>Status values capture the operational lifecycle (e.g., issued, expired,
* revoked, on hold).</li>
* </ul>
*
* @since 1.0
*/
package zeroecho.pki.api.credential;

76
pki/src/main/java/zeroecho/pki/api/issuance/BundleCommand.java Normal file
View File

@@ -0,0 +1,76 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.issuance;
import java.util.Optional;
import zeroecho.pki.api.PkiId;
/**
* Command to build a distributable bundle for an existing credential.
*
* <p>
* Bundles are constructed using chain selection rules, trust anchor selection,
* and optional compatibility profiles. This is especially relevant for
* cross-signing and migration scenarios.
* </p>
*
* @param credentialId credential id
* @param preferredTrustAnchorId optional preferred trust anchor id
* (implementation-defined)
* @param compatibilityProfileId optional compatibility profile id influencing
* chain selection
*/
public record BundleCommand(PkiId credentialId, Optional<PkiId> preferredTrustAnchorId,
Optional<String> compatibilityProfileId) {
/**
* Creates a bundle command.
*
* @throws IllegalArgumentException if inputs are invalid or optional containers
* are null
*/
public BundleCommand {
if (credentialId == null) {
throw new IllegalArgumentException("credentialId must not be null");
}
if (preferredTrustAnchorId == null) {
throw new IllegalArgumentException("preferredTrustAnchorId must not be null");
}
if (compatibilityProfileId == null) {
throw new IllegalArgumentException("compatibilityProfileId must not be null");
}
}
}

72
pki/src/main/java/zeroecho/pki/api/issuance/IssuanceInputs.java Normal file
View File

@@ -0,0 +1,72 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.issuance;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.attr.AttributeSet;
import zeroecho.pki.api.request.ParsedCertificationRequest;
/**
* Normalized inputs for issuance policy evaluation.
*
* @param issuerCaId issuer CA entity id
* @param request parsed certification request
* @param profileId profile id selected for issuance
* @param requestedOverrides user-requested overrides (may be empty but not
* null)
*/
public record IssuanceInputs(PkiId issuerCaId, ParsedCertificationRequest request, String profileId,
AttributeSet requestedOverrides) {
/**
* Creates issuance inputs for policy evaluation.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public IssuanceInputs {
if (issuerCaId == null) {
throw new IllegalArgumentException("issuerCaId must not be null");
}
if (request == null) {
throw new IllegalArgumentException("request must not be null");
}
if (profileId == null || profileId.isBlank()) {
throw new IllegalArgumentException("profileId must not be null/blank");
}
if (requestedOverrides == null) {
throw new IllegalArgumentException("requestedOverrides must not be null");
}
}
}

82
pki/src/main/java/zeroecho/pki/api/issuance/IssueEndEntityCommand.java Normal file
View File

@@ -0,0 +1,82 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.issuance;
import java.util.Optional;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.Validity;
import zeroecho.pki.api.attr.AttributeSet;
import zeroecho.pki.api.request.ParsedCertificationRequest;
/**
* Command to issue an end-entity credential from a parsed certification
* request.
*
* @param issuerCaId issuer CA entity id
* @param request parsed certification request
* @param profileId profile id governing issuance
* @param validityOverride optional requested validity override
* (policy-validated)
* @param overrides additional universal attribute overrides
* (policy-validated; may be empty but not null)
*/
public record IssueEndEntityCommand(PkiId issuerCaId, ParsedCertificationRequest request, String profileId,
Optional<Validity> validityOverride, AttributeSet overrides) {
/**
* Creates an issuance command.
*
* @throws IllegalArgumentException if inputs are invalid or optional container
* is null
*/
public IssueEndEntityCommand {
if (issuerCaId == null) {
throw new IllegalArgumentException("issuerCaId must not be null");
}
if (request == null) {
throw new IllegalArgumentException("request must not be null");
}
if (profileId == null || profileId.isBlank()) {
throw new IllegalArgumentException("profileId must not be null/blank");
}
if (validityOverride == null) {
throw new IllegalArgumentException("validityOverride must not be null");
}
if (overrides == null) {
throw new IllegalArgumentException("overrides must not be null");
}
}
}

68
pki/src/main/java/zeroecho/pki/api/issuance/ReissueCommand.java Normal file
View File

@@ -0,0 +1,68 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.issuance;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Command to reissue based on a stored issuance record.
*
* <p>
* The meaning of "issuance record" is implementation-defined (it may be derived
* from audit/store metadata). Reissue is useful for reproducing issuance under
* controlled changes.
* </p>
*
* @param issuanceRecordId issuance record id
* @param overrides universal attribute overrides (policy-validated; may
* be empty but not null)
*/
public record ReissueCommand(PkiId issuanceRecordId, AttributeSet overrides) {
/**
* Creates a reissue command.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public ReissueCommand {
if (issuanceRecordId == null) {
throw new IllegalArgumentException("issuanceRecordId must not be null");
}
if (overrides == null) {
throw new IllegalArgumentException("overrides must not be null");
}
}
}

76
pki/src/main/java/zeroecho/pki/api/issuance/RenewCommand.java Normal file
View File

@@ -0,0 +1,76 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.issuance;
import java.util.Optional;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.Validity;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Command to renew an existing credential.
*
* <p>
* Renewal typically retains continuity (same identity and key constraints)
* under policy-defined semantics. The implementation decides what "renew" means
* for a given framework and profile.
* </p>
*
* @param existingCredentialId credential id to renew
* @param validityOverride optional validity override (policy-validated)
* @param overrides universal attribute overrides (policy-validated;
* may be empty but not null)
*/
public record RenewCommand(PkiId existingCredentialId, Optional<Validity> validityOverride, AttributeSet overrides) {
/**
* Creates a renewal command.
*
* @throws IllegalArgumentException if inputs are invalid or optional container
* is null
*/
public RenewCommand {
if (existingCredentialId == null) {
throw new IllegalArgumentException("existingCredentialId must not be null");
}
if (validityOverride == null) {
throw new IllegalArgumentException("validityOverride must not be null");
}
if (overrides == null) {
throw new IllegalArgumentException("overrides must not be null");
}
}
}

78
pki/src/main/java/zeroecho/pki/api/issuance/ReplaceCommand.java Normal file
View File

@@ -0,0 +1,78 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.issuance;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.attr.AttributeSet;
import zeroecho.pki.api.request.ParsedCertificationRequest;
/**
* Command to replace an existing credential.
*
* <p>
* Replacement is used for scenarios such as compromise or identity attribute
* changes. Policy determines whether replacement is permitted and what
* continuity constraints apply.
* </p>
*
* @param existingCredentialId existing credential id
* @param newRequest new parsed request for the replacement credential
* @param profileId profile id governing issuance
* @param overrides universal attribute overrides (policy-validated;
* may be empty but not null)
*/
public record ReplaceCommand(PkiId existingCredentialId, ParsedCertificationRequest newRequest, String profileId,
AttributeSet overrides) {
/**
* Creates a replacement command.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public ReplaceCommand {
if (existingCredentialId == null) {
throw new IllegalArgumentException("existingCredentialId must not be null");
}
if (newRequest == null) {
throw new IllegalArgumentException("newRequest must not be null");
}
if (profileId == null || profileId.isBlank()) {
throw new IllegalArgumentException("profileId must not be null/blank");
}
if (overrides == null) {
throw new IllegalArgumentException("overrides must not be null");
}
}
}

65
pki/src/main/java/zeroecho/pki/api/issuance/VerificationPolicy.java Normal file
View File

@@ -0,0 +1,65 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.issuance;
import java.util.Optional;
/**
* Constraints for certification request verification.
*
* <p>
* This policy controls proof-of-possession requirements and may carry
* framework-specific verification modes via optional hints.
* </p>
*
* @param requireProofOfPossession whether proof-of-possession is required
* @param compatibilityProfileId optional compatibility profile hint for
* parsers/verifiers
*/
public record VerificationPolicy(boolean requireProofOfPossession, Optional<String> compatibilityProfileId) {
/**
* Creates a verification policy.
*
* @param requireProofOfPossession PoP requirement
* @param compatibilityProfileId optional compatibility profile id
* @throws IllegalArgumentException if {@code compatibilityProfileId} is null
*/
public VerificationPolicy {
if (compatibilityProfileId == null) {
throw new IllegalArgumentException("compatibilityProfileId must not be null");
}
}
}

61
pki/src/main/java/zeroecho/pki/api/issuance/package-info.java Normal file
View File

@@ -0,0 +1,61 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
/**
* Credential issuance domain model.
*
* <p>
* This package contains command objects and input types used to issue, renew,
* replace, and reissue credentials, as well as optional issuance verification
* policies. The operations are executed through
* {@link zeroecho.pki.api.IssuanceService}.
* </p>
*
* <h2>Command-driven operations</h2>
* <ul>
* <li>Issue end-entity credentials.</li>
* <li>Renew existing credentials.</li>
* <li>Replace credentials (e.g., due to key changes).</li>
* <li>Reissue credentials (policy-driven reissuance).</li>
* </ul>
*
* <p>
* Requests may originate from the request domain
* ({@code zeroecho.pki.api.request}) and issuance outcomes may be published
* and/or recorded in inventory.
* </p>
*
* @since 1.0
*/
package zeroecho.pki.api.issuance;

81
pki/src/main/java/zeroecho/pki/api/package-info.java Normal file
View File

@@ -0,0 +1,81 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
/**
* Public, framework-agnostic PKI API.
*
* <p>
* This package provides stable entry points and core value types for operating
* a PKI instance. The API is intentionally independent of any concrete
* certificate framework (for example X.509), allowing multiple frameworks to be
* integrated via SPIs in {@code zeroecho.pki.spi.*}.
* </p>
*
* <h2>Design principles</h2>
* <ul>
* <li><strong>Framework independence:</strong> the API models PKI concepts (CA,
* issuance, revocation, status objects, publication, backup/restore) without
* binding to a single certificate technology.</li>
* <li><strong>Explicit commands and queries:</strong> mutable operations are
* expressed as command objects and retrieval via query objects in
* subpackages.</li>
* <li><strong>Safety and auditability:</strong> security-relevant operations
* are designed to be auditable; sensitive data must never be exposed by API
* abstractions.</li>
* </ul>
*
* <h2>Key entry points</h2>
* <ul>
* <li>{@link zeroecho.pki.api.CaService}</li>
* <li>{@link zeroecho.pki.api.CertificationRequestService}</li>
* <li>{@link zeroecho.pki.api.IssuanceService}</li>
* <li>{@link zeroecho.pki.api.RevocationService}</li>
* <li>{@link zeroecho.pki.api.StatusObjectService}</li>
* <li>{@link zeroecho.pki.api.PublicationService}</li>
* <li>{@link zeroecho.pki.api.ProfileService}</li>
* <li>{@link zeroecho.pki.api.PolicyService}</li>
* <li>{@link zeroecho.pki.api.ImportExportService}</li>
* <li>{@link zeroecho.pki.api.BackupService}</li>
* </ul>
*
* <p>
* Subpackages further organize domain models: {@code ca}, {@code issuance},
* {@code request}, {@code revocation}, {@code status}, {@code publication},
* {@code profile}, {@code policy}, {@code transfer}, plus attribute and audit
* domains in {@code attr} and {@code audit}.
* </p>
*
* @since 1.0
*/
package zeroecho.pki.api;

80
pki/src/main/java/zeroecho/pki/api/policy/PolicyDecision.java Normal file
View File

@@ -0,0 +1,80 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.policy;
import java.util.List;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Policy decision including optional modifications to be applied to an
* operation.
*
* <p>
* The {@code appliedOverrides} attribute set is used to communicate
* policy-enforced adjustments (e.g., constrained validity, normalized
* attributes). It must not contain secrets.
* </p>
*
* @param decisionId stable decision identifier for correlation and
* explainability
* @param status decision outcome status
* @param messages non-sensitive operator-readable messages
* @param appliedOverrides policy-enforced overrides to be applied downstream
*/
public record PolicyDecision(PkiId decisionId, PolicyDecisionStatus status, List<String> messages,
AttributeSet appliedOverrides) {
/**
* Creates a policy decision.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public PolicyDecision {
if (decisionId == null) {
throw new IllegalArgumentException("decisionId must not be null");
}
if (status == null) {
throw new IllegalArgumentException("status must not be null");
}
if (messages == null) {
throw new IllegalArgumentException("messages must not be null");
}
if (appliedOverrides == null) {
throw new IllegalArgumentException("appliedOverrides must not be null");
}
}
}

57
pki/src/main/java/zeroecho/pki/api/policy/PolicyDecisionStatus.java Normal file
View File

@@ -0,0 +1,57 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.policy;
/**
* Outcome status of a policy evaluation.
*/
public enum PolicyDecisionStatus {
/**
* Operation is allowed under current policy.
*/
ALLOW,
/**
* Operation is denied under current policy.
*/
DENY,
/**
* Operation is allowed, but policy requires modifications (e.g., validity
* truncation).
*/
ALLOW_WITH_MODIFICATIONS
}

62
pki/src/main/java/zeroecho/pki/api/policy/PolicyTrace.java Normal file
View File

@@ -0,0 +1,62 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.policy;
import java.util.List;
import zeroecho.pki.api.PkiId;
/**
* Explainability trace for a policy decision.
*
* @param decisionId decision id this trace explains
* @param steps ordered evaluation steps
*/
public record PolicyTrace(PkiId decisionId, List<PolicyTraceStep> steps) {
/**
* Creates a policy trace.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public PolicyTrace {
if (decisionId == null) {
throw new IllegalArgumentException("decisionId must not be null");
}
if (steps == null) {
throw new IllegalArgumentException("steps must not be null");
}
}
}

65
pki/src/main/java/zeroecho/pki/api/policy/PolicyTraceStep.java Normal file
View File

@@ -0,0 +1,65 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.policy;
import java.util.List;
/**
* Single evaluation step within a policy trace.
*
* @param ruleId stable rule identifier (implementation-defined)
* @param outcome human-readable outcome string (e.g., "ALLOW", "DENY",
* "MODIFY")
* @param notes non-sensitive explanatory notes
*/
public record PolicyTraceStep(String ruleId, String outcome, List<String> notes) {
/**
* Creates a policy trace step.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public PolicyTraceStep {
if (ruleId == null || ruleId.isBlank()) {
throw new IllegalArgumentException("ruleId must not be null/blank");
}
if (outcome == null || outcome.isBlank()) {
throw new IllegalArgumentException("outcome must not be null/blank");
}
if (notes == null) {
throw new IllegalArgumentException("notes must not be null");
}
}
}

53
pki/src/main/java/zeroecho/pki/api/policy/package-info.java Normal file
View File

@@ -0,0 +1,53 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
/**
* Policy decision and trace model.
*
* <p>
* This package defines the core policy decision objects and trace structures
* used to explain and audit policy evaluation outcomes. It is consumed via
* {@link zeroecho.pki.api.PolicyService}.
* </p>
*
* <h2>Explainability</h2>
* <p>
* Policy traces are intended to provide human- and machine-readable reasoning
* without exposing sensitive data. Trace steps must remain deterministic and
* stable for audit retention.
* </p>
*
* @since 1.0
*/
package zeroecho.pki.api.policy;

97
pki/src/main/java/zeroecho/pki/api/profile/CertificateProfile.java Normal file
View File

@@ -0,0 +1,97 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.profile;
import java.time.Duration;
import java.util.List;
import java.util.Optional;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.attr.AttributeId;
/**
* Defines issuance constraints and mapping hints for a class of credentials.
*
* <p>
* A profile is referenced by {@code profileId} during issuance. It defines
* which universal attributes are required or allowed, and provides limits such
* as maximum validity. Framework backends may use the profile as a source of
* mapping hints when translating universal attributes into framework-specific
* fields/extensions.
* </p>
*
* <p>
* Profiles must not include secrets.
* </p>
*
* @param profileId stable profile identifier
* @param formatId framework/format supported by the profile
* @param displayName human-readable name
* @param requiredAttributes list of required attribute identifiers
* @param optionalAttributes list of optional attribute identifiers
* @param maxValidity optional maximum validity allowed by the profile
* @param active whether the profile is active for issuance
*/
public record CertificateProfile(String profileId, FormatId formatId, String displayName,
List<AttributeId> requiredAttributes, List<AttributeId> optionalAttributes, Optional<Duration> maxValidity,
boolean active) {
/**
* Creates a certificate profile.
*
* @throws IllegalArgumentException if inputs are invalid or optional container
* is null
*/
public CertificateProfile {
if (profileId == null || profileId.isBlank()) {
throw new IllegalArgumentException("profileId must not be null/blank");
}
if (formatId == null) {
throw new IllegalArgumentException("formatId must not be null");
}
if (displayName == null || displayName.isBlank()) {
throw new IllegalArgumentException("displayName must not be null/blank");
}
if (requiredAttributes == null) {
throw new IllegalArgumentException("requiredAttributes must not be null");
}
if (optionalAttributes == null) {
throw new IllegalArgumentException("optionalAttributes must not be null");
}
if (maxValidity == null) {
throw new IllegalArgumentException("maxValidity must not be null");
}
}
}

61
pki/src/main/java/zeroecho/pki/api/profile/ProfileQuery.java Normal file
View File

@@ -0,0 +1,61 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.profile;
import java.util.Optional;
import zeroecho.pki.api.FormatId;
/**
* Query constraints for listing profiles.
*
* @param formatId optional format filter
* @param profileId optional profile id filter
* @param activeOnly optional filter (true -> only active profiles, false ->
* only inactive, empty -> all)
*/
public record ProfileQuery(Optional<FormatId> formatId, Optional<String> profileId, Optional<Boolean> activeOnly) {
/**
* Creates a profile query.
*
* @throws IllegalArgumentException if any optional container is null
*/
public ProfileQuery {
if (formatId == null || profileId == null || activeOnly == null) {
throw new IllegalArgumentException("optional fields must not be null");
}
}
}

51
pki/src/main/java/zeroecho/pki/api/profile/package-info.java Normal file
View File

@@ -0,0 +1,51 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
/**
* Certificate and credential profiles.
*
* <p>
* This package contains profile model objects and query types describing
* constraints and defaults used during issuance. Profiles are managed through
* {@link zeroecho.pki.api.ProfileService}.
* </p>
*
* <p>
* Profiles are framework-agnostic by design and are mapped into concrete
* framework constructs during credential creation.
* </p>
*
* @since 1.0
*/
package zeroecho.pki.api.profile;

61
pki/src/main/java/zeroecho/pki/api/publication/PublicationQuery.java Normal file
View File

@@ -0,0 +1,61 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.publication;
import java.time.Instant;
import java.util.Optional;
/**
* Query constraints for listing publication records.
*
* @param targetType optional target type filter
* @param after optional lower bound for time
* @param before optional upper bound for time
* @param objectKind optional object kind filter
*/
public record PublicationQuery(Optional<PublicationTargetType> targetType, Optional<Instant> after,
Optional<Instant> before, Optional<String> objectKind) {
/**
* Creates a publication query.
*
* @throws IllegalArgumentException if any optional container is null
*/
public PublicationQuery {
if (targetType == null || after == null || before == null || objectKind == null) {
throw new IllegalArgumentException("optional fields must not be null");
}
}
}

86
pki/src/main/java/zeroecho/pki/api/publication/PublicationRecord.java Normal file
View File

@@ -0,0 +1,86 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.publication;
import java.time.Instant;
import zeroecho.pki.api.PkiId;
/**
* Persisted record of a publication attempt.
*
* <p>
* Publication records support operational troubleshooting, auditability, and
* re-publication workflows.
* </p>
*
* @param publicationId publication id
* @param time time when publication was attempted
* @param target publication target
* @param objectId published object id (credential, CA materials, status
* object)
* @param objectKind non-empty logical kind string (e.g., "CREDENTIAL",
* "CA_MATERIALS", "STATUS_OBJECT")
* @param status publication outcome
*/
public record PublicationRecord(PkiId publicationId, Instant time, PublicationTarget target, PkiId objectId,
String objectKind, PublicationStatus status) {
/**
* Creates a publication record.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public PublicationRecord {
if (publicationId == null) {
throw new IllegalArgumentException("publicationId must not be null");
}
if (time == null) {
throw new IllegalArgumentException("time must not be null");
}
if (target == null) {
throw new IllegalArgumentException("target must not be null");
}
if (objectId == null) {
throw new IllegalArgumentException("objectId must not be null");
}
if (objectKind == null || objectKind.isBlank()) {
throw new IllegalArgumentException("objectKind must not be null/blank");
}
if (status == null) {
throw new IllegalArgumentException("status must not be null");
}
}
}

66
pki/src/main/java/zeroecho/pki/api/publication/PublicationResult.java Normal file
View File

@@ -0,0 +1,66 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.publication;
import java.util.List;
import zeroecho.pki.api.PkiId;
/**
* Result of a publish operation.
*
* @param publicationId publication record id
* @param status outcome status
* @param notes non-sensitive operator-readable notes
*/
public record PublicationResult(PkiId publicationId, PublicationStatus status, List<String> notes) {
/**
* Creates a publication result.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public PublicationResult {
if (publicationId == null) {
throw new IllegalArgumentException("publicationId must not be null");
}
if (status == null) {
throw new IllegalArgumentException("status must not be null");
}
if (notes == null) {
throw new IllegalArgumentException("notes must not be null");
}
}
}

57
pki/src/main/java/zeroecho/pki/api/publication/PublicationStatus.java Normal file
View File

@@ -0,0 +1,57 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.publication;
/**
* Publication outcome status.
*/
public enum PublicationStatus {
/**
* Artifact has been published successfully.
*/
PUBLISHED,
/**
* Publication was skipped (e.g., already published, policy decision, target not
* applicable).
*/
SKIPPED,
/**
* Publication failed.
*/
FAILED
}

70
pki/src/main/java/zeroecho/pki/api/publication/PublicationTarget.java Normal file
View File

@@ -0,0 +1,70 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.publication;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Describes where and how to publish an artifact.
*
* <p>
* The {@code targetId} identifies a configured target instance. Additional
* configuration is carried in {@code attributes}. Secrets must not be carried
* in attributes intended for publication.
* </p>
*
* @param type destination type
* @param targetId target identifier (implementation-defined)
* @param attributes target configuration/hints (may be empty but not null)
*/
public record PublicationTarget(PublicationTargetType type, String targetId, AttributeSet attributes) {
/**
* Creates a publication target.
*
* @throws IllegalArgumentException if inputs are invalid
*/
public PublicationTarget {
if (type == null) {
throw new IllegalArgumentException("type must not be null");
}
if (targetId == null || targetId.isBlank()) {
throw new IllegalArgumentException("targetId must not be null/blank");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

66
pki/src/main/java/zeroecho/pki/api/publication/PublicationTargetType.java Normal file
View File

@@ -0,0 +1,66 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.publication;
/**
* Classifies the publication destination type.
*/
public enum PublicationTargetType {
/**
* Publish to a filesystem location.
*/
FILESYSTEM,
/**
* Publish to an LDAP directory.
*/
LDAP,
/**
* Publish via an HTTP(S) endpoint.
*/
HTTP,
/**
* Publish to an object store (S3-like).
*/
OBJECT_STORE,
/**
* Custom target type implemented by a publisher plugin.
*/
CUSTOM
}

53
pki/src/main/java/zeroecho/pki/api/publication/package-info.java Normal file
View File

@@ -0,0 +1,53 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
/**
* Publication domain model.
*
* <p>
* This package defines publication targets and records describing how PKI
* artifacts are distributed to relying parties or infrastructure components
* (repositories, directories, endpoints, etc.). Publication is orchestrated
* through {@link zeroecho.pki.api.PublicationService}.
* </p>
*
* <h2>Artifacts</h2>
* <p>
* Publication may include certificates, chains, status objects, and related
* metadata. The concrete transport is framework- and deployment-specific.
* </p>
*
* @since 1.0
*/
package zeroecho.pki.api.publication;

74
pki/src/main/java/zeroecho/pki/api/request/CertificationRequest.java Normal file
View File

@@ -0,0 +1,74 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.request;
import zeroecho.pki.api.EncodedObject;
import zeroecho.pki.api.FormatId;
/**
* Opaque certification request container.
*
* <p>
* This type transports a request payload and declares the request format via
* {@link FormatId}. A framework backend parses and normalizes the payload into
* {@link ParsedCertificationRequest}.
* </p>
*
* <p>
* For X.509, the request is typically a PKCS#10 CSR. Other frameworks may
* define different request syntaxes.
* </p>
*
* @param formatId request/credential framework id
* @param encoded encoded request payload
*/
public record CertificationRequest(FormatId formatId, EncodedObject encoded) {
/**
* Creates a certification request.
*
* @param formatId request format id
* @param encoded encoded request payload
* @throws IllegalArgumentException if inputs are null
*/
public CertificationRequest {
if (formatId == null) {
throw new IllegalArgumentException("formatId must not be null");
}
if (encoded == null) {
throw new IllegalArgumentException("encoded must not be null");
}
}
}

114
pki/src/main/java/zeroecho/pki/api/request/ParsedCertificationRequest.java Normal file
View File

@@ -0,0 +1,114 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.request;
import java.util.Optional;
import zeroecho.pki.api.EncodedObject;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.PkiId;
import zeroecho.pki.api.SubjectRef;
import zeroecho.pki.api.Validity;
import zeroecho.pki.api.attr.AttributeSet;
/**
* Normalized representation of a certification request.
*
* <p>
* This record is produced by a framework-specific request parser. It contains a
* minimal set of mandatory core fields required by the PKI runtime, plus a
* universal typed {@link AttributeSet} that carries additional request
* attributes in a framework-neutral manner.
* </p>
*
* <p>
* The PKI runtime is expected to apply policy and profile constraints before
* issuance.
* </p>
*
* @param requestId stable identifier for the request (typically
* derived from the request payload fingerprint)
* @param formatId framework/format identifier
* @param subjectRef normalized subject reference for policy and
* inventory correlation
* @param publicKeyInfo requested public key information (SPKI DER
* preferred where applicable)
* @param requestedValidity optional validity requested by the subject; policy
* may override or deny
* @param requestedProfileId optional profile hint; policy may override or deny
* @param attributes universal typed attributes extracted from the
* request
*/
public record ParsedCertificationRequest(PkiId requestId, FormatId formatId, SubjectRef subjectRef,
EncodedObject publicKeyInfo, Optional<Validity> requestedValidity, Optional<String> requestedProfileId,
AttributeSet attributes) {
/**
* Creates a parsed certification request.
*
* @param requestId stable request id
* @param formatId format id
* @param subjectRef normalized subject reference
* @param publicKeyInfo requested public key info
* @param requestedValidity optional requested validity
* @param requestedProfileId optional requested profile id
* @param attributes extracted attributes
* @throws IllegalArgumentException if mandatory inputs are null or optional
* containers are null
*/
public ParsedCertificationRequest {
if (requestId == null) {
throw new IllegalArgumentException("requestId must not be null");
}
if (formatId == null) {
throw new IllegalArgumentException("formatId must not be null");
}
if (subjectRef == null) {
throw new IllegalArgumentException("subjectRef must not be null");
}
if (publicKeyInfo == null) {
throw new IllegalArgumentException("publicKeyInfo must not be null");
}
if (requestedValidity == null) {
throw new IllegalArgumentException("requestedValidity must not be null");
}
if (requestedProfileId == null) {
throw new IllegalArgumentException("requestedProfileId must not be null");
}
if (attributes == null) {
throw new IllegalArgumentException("attributes must not be null");
}
}
}

67
pki/src/main/java/zeroecho/pki/api/request/ProofOfPossessionResult.java Normal file
View File

@@ -0,0 +1,67 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.request;
import java.util.Optional;
/**
* Result of proof-of-possession (PoP) verification.
*
* <p>
* The {@code details} field is intended for operator diagnostics and must not
* contain secrets.
* </p>
*
* @param status verification outcome status
* @param details optional non-sensitive diagnostic information
*/
public record ProofOfPossessionResult(ProofOfPossessionStatus status, Optional<String> details) {
/**
* Creates a PoP verification result.
*
* @param status outcome status
* @param details optional diagnostic details (non-sensitive)
* @throws IllegalArgumentException if {@code status} or {@code details} is null
*/
public ProofOfPossessionResult {
if (status == null) {
throw new IllegalArgumentException("status must not be null");
}
if (details == null) {
throw new IllegalArgumentException("details must not be null");
}
}
}

66
pki/src/main/java/zeroecho/pki/api/request/ProofOfPossessionStatus.java Normal file
View File

@@ -0,0 +1,66 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.request;
/**
* Outcome of proof-of-possession (PoP) verification.
*/
public enum ProofOfPossessionStatus {
/**
* Proof-of-possession has been successfully verified.
*/
VERIFIED,
/**
* Proof-of-possession evidence is not present.
*
* <p>
* This is acceptable only if policy allows it.
* </p>
*/
NOT_PRESENT,
/**
* Proof-of-possession evidence is present but invalid.
*/
FAILED,
/**
* Proof-of-possession verification is not supported for the given request type
* or framework.
*/
NOT_SUPPORTED
}

74
pki/src/main/java/zeroecho/pki/api/request/RequestQuery.java Normal file
View File

@@ -0,0 +1,74 @@
/*******************************************************************************
* Copyright (C) 2025, 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.
******************************************************************************/
package zeroecho.pki.api.request;
import java.time.Instant;
import java.util.Optional;
import zeroecho.pki.api.FormatId;
import zeroecho.pki.api.SubjectRef;
/**
* Query constraints for searching stored certification requests.
*
* @param formatId optional framework filter
* @param subjectRef optional subject filter
* @param createdAfter optional lower bound (inclusive) for request creation
* time
* @param createdBefore optional upper bound (exclusive) for request creation
* time
* @param profileId optional profile filter (requested or resolved profile
* id depending on implementation)
*/
public record RequestQuery(Optional<FormatId> formatId, Optional<SubjectRef> subjectRef, Optional<Instant> createdAfter,
Optional<Instant> createdBefore, Optional<String> profileId) {
/**
* Creates a request query.
*
* @param formatId optional format filter
* @param subjectRef optional subject filter
* @param createdAfter optional lower time bound
* @param createdBefore optional upper time bound
* @param profileId optional profile id filter
* @throws IllegalArgumentException if any optional container is null
*/
public RequestQuery {
if (formatId == null || subjectRef == null || createdAfter == null || createdBefore == null
|| profileId == null) {
throw new IllegalArgumentException("optional fields must not be null");
}
}
}

Some files were not shown because too many files have changed in this diff Show More